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PREFACE 


MANUAL  OBJECTIVES 

The  RSX-llM/M-PLUS  Execut  ive  Reference  Manual  describes  the  system 
directives  that  allow  experienced  MACRO-11  and  FORTRAN  progianimers  to 
use  Executive  services  to  control  the  execution  and  interaction  of 
tasks. 


INTENDED  AUDIENCE 

The  intended  audience  for  this  manual  are  software  developers  who  are 
experienced  usors  of  MA'7R0-11  or  FORTRAN  for  user  task  generation. 
Information  contained  in  this  manual  is  intended  for  reference  only; 
no  attempt  is  made  to  describe  the  procedures  involved  in  developing 
user  tasks  beyond  the  detailed  reference  information  normally  required 
for  directive  use.  However,  Chapters  1  through  4  do  contain  much 
information  that  will  aid  in  better  understanding  how  directives  can 
be  effectively  used  in  the  RSX-llM/M-PLUvS  multitasking  environment. 
Convenient  quick-reference  material  is  included  in  appendixes  at  the 
end  of  the  manual  for  use  by  the  mote  advanced  RSX-llM/M-PL'JS 
programmer . 


t:TRUCTURE  OF  TMIS  DOCUMENT 

A  Summary   Of   Technical   Changes   provides  the   experienced   RSX-llM 

/RSX-1 IM-PLUS   user  with  a  quick  summary  of  chanf  3S  to  system  software 

since  the  previous  version  of  this  manual.  Comments  are  general  and 
serve  only  as  a  guide  to  areas  of  change. 

Chapter  1  defines  system  directives  and  describes  their  use  in  both 
MACP.O-11  and  FORTRAN  programs. 

Chapter  2  defines  significant  evencs,  event  flags,  system  traps,  and 
stop-bit  synchronization,  and  describes  their  relation^nip  to  system 
di  rect ives . 

Chapter  3  intrr duces  the  concept  of  extended  logical  address  space 
within  the  framework  of  memory  management  directives. 

Chapter  -5  introduces  the  concept  of  parent/of  fspr  iiig  tasking, 
including  associated  directives,  generated  data  structures,  and  task 
commun  ications. 

Chapter  5  contains  a  shore  summary  of  all  directives,  arranged 
according  to  their  functional  categories.  The  summary  is  followed  by 
detailed  descriptions  of  each  system  directive  arranged  alphabetically 
according  to  macto  call. 


IX 


PREFACE 

Appendix  A  contains  directives  arranged  alphabetically  according  to 
macro  call.  Abbreviated  specifications  include  directive  name, 
FORTRAN  call,  macro  call,  and  parameters  only. 

Appendix  B  lists  the  standard  error  codes  returned  by  the  RSX-llM  or 
RSX-llM-PLUS  Exacutiv  '. 

Appendix  C  lists  Directive  Identification  Codes  for  all  directives  in 
the  saiT.e  octal  values  that  they  have  i  ii  the  Directive  Parameter  Block. 
A  description  of  how  the  values  are  obtained  is  included. 

Appendix  D  lists  all   directives,   the   operating   systems   where  the 

individual     directives    are    available    (RSX-llS,    RSX-llM,  or 

RSX-llM-PLUS),  and  the  SYSGEN  option  required  (if  applicable)  to 
obtain  that  directive  support. 


ASSOCIATED  DOCUMENTS 

Manuals  that  are  prerequisite  sources  of  information   for   readers  of 

this   manual   are:    the   RSX-1 IM/M-PLUS   Task   Builder  Manual  and  the 

PDP-11  MACHO-11  Language  Reference  Manual ,"  the  lAS/RSX-U  FORTRAN  IV 
User's  Guide,  or  the  FORTRAN-77  User's  Guide. 

Other  documents  related  to  the  contents  of  this  manual  are  described 
briefly  in  the  appropriate  documentation  directory  supplied  with  the 
software  kit. 


CONVENTIONS  USED  IN  THIS  DOCUMENT 

Whenever  necessary,  information  that  is  applicable  to  a  specific 
operating  system  (RSX-llM  or  RSX-llM-PLUS)  is  clearly  indicated.  In 
addition,  for  ease  of  reference,  those  portions  of  text  thst  apply  to 
RSX-llM-PLUS  only  are  indicated  by  background  shading  on  the  printed 
page. 


SUMMARY  OF  TECHNICAL  CHANGES 


This  revision  of  the  Rf.X-1  IM/M-PLUS  Executive  Reference  Manual 
contains  changes  and  additions  to  document  two  operating 
systems:   RSX-llM  V4.0  and  RSX-llM-PLUS  V2.0, 

The  following  new  directives  have  been  added  to  botb  RSX-llM  and 
RSX-llM-PLUS: 

Request  and  Pass  Offspring  Information 

Send,  Request  and  Pass  Offspring  Control  Block 

Set  System  Time 

Unlock  Group  Global  Event  Flags 

The  following  directives  that  were  formerly  specific  to  RSX-llM-PLUS 
are  now  common  to  both  operating  systems: 

Send,  Request  and  Connect 
Specify  Requested  Exit  AST 

The  following  new  directives  have  been  added  to  RSX-llM-PLUS: 

Checkpoint  Common  Region 

Map  Supervisor  D-Space 

Move  to/from  Supervisor  or  User  I-  or  D-Space 

Read  Single  Event  Fiag 

Variable  Send,  Request  and  Connect 

Send  Next  Command 

There  are  also  four  new  directives  that  support  alternate  Command  Line 
Interpreters.  These  CLI  support  directives  are  common  to  both 
operating  systems: 

Get  Command  for  Command  Line  Interpreter 
Get  Command  Interpreter  Information 
Set  Command  Line  Interpreter 
Specify  Command  Arrival  AST 

The  description  of  the  Spawn  directive  now  includes  an  example  that 
shows  how  to  use  parent/offspring  tasking  to  provide  AST  service 
routines  In  FORTRAN.  Guidelines  for  coding  FORTRAN  AST  service 
routines  are  Included  In  Chapter  1. 
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CHAPTER  1 
USING  SYSTEM  DIRECTIVES 


This  chapter  describes  the  use  of  system  directives  and  the  ways  in 
which  they  are  processed.  Some  of  the  Executive  services  described  in 
this  manual  are  optional  RSX-llS,  RSX-llM,  or  RSX-llM-PLUS  features 
and  may  not  be  present  in  the  system  you  are  currently  using.  The 
discussion  of  the  system  directives  assumes  that  all  possible  features 
are  present  in  your  system.  See  the  appropriate  system  generation 
manual  for  a  list  of  optional  features. 


1.  1   INTRODUCTION 

When  a  task  requests  the  Executive  to  perform  an  indicated  operation, 
this  process  is  called  a  system  directive.  You  use  the  directives  to 
control  the  execution  and  interaction  of  tasks.  If  you  are  a  MACRO-11 
programmer,  you  usually  issue  directives  in  the  form  of  macros  defined 
in  the  system  macro  library.  If  you  are  a  FORTRAN  programmer,  issue 
system  directives  in  the  form  of  calls  to  subroutines  contained  in  the 
system  object  module  library. 

System  directives  enable  tasks  to: 

»  Obtain  task  and  system  information 

•  Measure  time  intervals 

•  Perform  I/O  functions 

•  Spawn  other  tasks 

•  Communicate  and  synchronize  with  other  tasks 

•  Manipulate  a  task's  logical  and  virtual  address  space 

•  Suspend  and  resume  execution 

•  Ex  it 

Directives  -ire  implemented  by  the  EMT  .177  instruction.  EMT  0  through 
EMT  376  (or  375  for  unmapped  tasks  and  mapped  privileged  tasks)  are 
considered  to  be  non-RSX  EMT  synchronous  system  traps.  They  cause  the 
Executive  to  abort  the  task  unless  the  task  has  specified  that  it 
wants  to  receive  control  when  such  traps  occur. 

If  you  are  a  MACRO-11  programmer,  use  the  system  directive  macros 
supplied  in  the  system  macro  library  for  directive  calls,  rather  than 
hand-coding  calls  to  directives.  Then  you  need  only  reassemble  the 
program  to  incorporate  any  changes  in  the  directive  specifications. 

Sections  1.2,  1.3,  and  1.6  are  intended  for  all  users.  Section  1.4 
specifically  describes  the  use  of  macros,  while  Section  1.5  describes 
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the  use  of  FORTRAN  subroutine  calls.  Programmers  using  other 
supported  languages  should  refer  to  the  appropriate  language  reference 
manual  supplied  by  DIGITAL. 


1.2   DIRECTIVE  PROCESSING 

Processing  a  system  directive  involves  four  steps: 

1.  The  user  task  issues  a  directive  with  arguments  that  are  only 
used  by  the  Executive.  The  directive  code  and  parameters 
the";  the  tdsk  supplies  to  the  system  are  known  as  the 
Directive  Parameter  Block  (DPB) .  The  DPD  can  be  either  on 
the  user  task's  stack  or  in  a  user  task's  data  section. 

2.  The  Executive  receives  an  EMT  377  generated  by  the  directive 
macro  (or  a  DIR$  macro)  or  FORTRAN  subroutine. 

3.  The  Executive  processes  the  directive, 

4.  The  Executive  returns  directive  status  information  to  the 
task's  Directive  Status  Word  (DtJW). 

Note  that  the  Executive  preserves  all  task  registers  when  a  task 
issues  a  directive. 

The  user  task  issues  an  EMT  377  (generated  by  the  directive)  together 
with  the  address  of  a  DPB  or  a  DPB  itself,  on  the  top  of  the  issuing 
task's  stack.  When  the  stack  contains  a  DPB  address,  the  Executive 
removes  the  address  after  processing  the  directive,  and  the  DPB  itself 
remains  unchanged.  When  the  stack  contains  the  actual  DPB  rather  than 
a  DPB  address,  the  Executive  removes  the  DPB  from  the  stack  after 
processing  the  directive. 

The  first  word  of  each  DPB  contains  a  Directive  Identification  Code 
(DIC)  byte,  and  a  DPB  size  byte.  The  DIC  indicates  which  directive  is 
to  be  ptrformed;  the  size  byte  indicates  the  DPB  length  In  words. 
The  DIC  Is  In  the  low-order  byte  of  the  word,  and  the  size  is  in  the 
high-order  byte. 

The  DIC  is  always  an  odd-numbered  value.  This  allows  the  Executive  to 
determine  whether  the  word  on  the  top  of  the  stack  (before  EMT  377  was 
issued)  was  the  address  of  the  DPB  (even-numbered  value)  or  the  first 
word  of  the  DPB  (odd-numberc»d  value). 

The  Executive  normally  returns  control  to  the  Instruction  follovdnq 
the  EMT.  Exceptions  to  this  are  directives  that  result  in  an  exit 
from  the  task  that  Issued  them  and  an  Asynchr.inous  System  Trap  (AST) 
ex  It . 

The  Executive  also  clears  or  sets  the  Carry  bit  .n  the  Processor 
Status  Word  (PSW)  to  indicate  acceptance  or  rejection,  respectively, 
of  the  directive.  The  DSW,  addressed  symbolically  as  $DSWl,  is  set  to 
indicate  a  more  specific  cause  for  acceptance  or  rejection  of  the 
directive.  The  DSW  usually  has  a  value  of  +1  foi  acceptance  and  a 
range  of  negative  values  for  rejection  (except  ionti  are  success  return 
codes  for  the  directives  CLEFS,  SETFS,  and  GPRT$,  among  others). 
RSX-1 IM/Y-PLUS  associate  DSW  values  with  symbols,  using  mnemonics  that 
report  either  successful  completion  or  the   cause   of   an   error   (see 


1.  The  Task  Builder  resolves  the  address  of   SDSW.    Users   addressing 

the   DSW  with  a  physical  address  are  not  guaranteed  compatibility  with 

IAS  and  may  experience  incompatibilities  with  future  RSX-1 IM  releases. 
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Section  1.3).  (The  Instrument  Society  of  America  (ISA)  FORTRAN  calls 
CALL  TTART  and  CALL  WAIT  are  exceptions,  since  ISA  requires  positive 
numeric  error  codes.  See  Sections  5.3.57  and  5.3.41  for  details;  the 
specific  return  values  are  listed  there  with  each  directive.) 

In  the  case  of  successful  Exit  directives,  the  Executive  does  not,  of 
course,  return  control  to  the  task.^.  If  an  Exit  directive  fails, 
however,  control  is  returned  to  the  task  with  an  error  status  in  the 
DSW. 

On  Exit,  the  Executive  frees  task  resources  as  followc: 

Detaches  all  attached  devices 

Flushes  the  AST  queue  and  despecifies  all  specified  ASTs 

Flushes  the  receive  and  rece I ve-by-ref erence  queues 

Flushes  the  clock  queue  for  outstanding  Mark  Time  requests  for 
the  task 

Closes  all  open  files  (files  open  for  write  access  are  locked) 

Detaches  all  attached  regions  except  in  the  case   of   a   fixed 
task,  where  no  detaching  occurs 

Runs  down  the  task's  I/O 

Deaccesses  the  group  global  event  flags  for  the  task's  group 

Disconnects  from  interrupts 

Flushes  all  outstanding  CLI  command  buffers  for  the  task 

Breaks  the  connection  with  any  offspring  tasks 

Marks  for  deallocation  all  virtual   terminal   units   that   the 
task  has  created 

Frees  the  task's  memory  if  the  task  was  not  fixed 

If  the  Executive  rejects  a  directive,  it  usually  does  not  clear  or  set 

any   specified  event  flag.   Thus,  the  task  may  wait  indefinitely  if  it 

indiscriminately  executes  a  Wait   For  directive   corresponding   to   a 

previously  issued  Mark  Time  directive  that  the  Executive  has  rejected. 

You  should  always  ensure  that  a  directive  has  been  completed 
successful ly. 


1. 3   ERROR  RETURNS 

As  stated  above,  RSX-1 IM/M-PLUS  associate  the  error  codes  with 
mnv»monics  that  report  the  cause  of  thf^  error.  In  the  text  of  the 
manual,  the  mnemonics  are  used  exclusively.  The  macro  DRERRS,  which 
is  expanded  in  Appendix  B,  provides  a  correspondence  between  each 
mnemonic  and  its  numeric  value. 

Appendix  B  also  gives  the  mv.'aning  of  each  error  rode.  In  addition, 
each  directive  description  in  Chapter  5  contains  specific, 
directive-related  interpretations  of  the  error  codes. 
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1.1   USING  THE  DIRECTIVE  MACROS 

If  you  are  programming  in  MACRO-11,  you  must  decide  how  to  create  the 
DPB  before  you  issue  a  directive.  The  DPB  iray  either  be  created  on 
the  stack  at  run  time  (see  Section  1.4.1.3,  which  describes  the  $S 
form,  of  directive)  or  created  in  a  data  section  at  assembly  time  (see 
Sections  1.4.1.1  and  1.4.1.2,  which  desrribe  the  $  fo:  .r.  and  SC  form, 
respectively).  If  parameters  vary  and  the  code  must  be  reentrant,  the 
DPB  must  bf  created  on  the  stack. 


Figures  1-1  and  1-2  illustrate  the   alternative   directives 
show  the  relationship  between  the  stack  pointer  and  the  DPB. 


ar.d   a]  so 


MOV 
EMT 


«  ADOH  iSPi 

37; 


SP 


ADDRESS  Of  DPB 


DPB 

ITEMS 

"il^F 

Die 

DPB 


INCREASING 

MEMOHY 

ADDRESSES 


STACK 
GROWTH 


Figure  1-1   Directive  Parameter  Block  (DPB)  Pointer  on  th*;  Stack 


MOV 

XX.  (SP) 

PUSH  REOUIRED 

DPB  ITEMS  ON  THE 

STACK  IN 

REVERSE  ORDER 

MOV 

(PC).    (SP 

BYTE                     DICSIZE 

EMT 

3;; 

SP 


i 

1 
1 

1                   DPB 

(                  ITEMS 

1        SIZE 

I. 

... 
Die 

H 


STACK 
GROWTH 


INCREASING 

MEMORY 

ADDRESSES 


Figure    1-2       Directive    Parameter    BIock     mpB)     on    ♦he    St.Trrk 
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1.4.1  Macro  Name  Conventions 


When    you   are    programming    in   MACRO-11, 
including      directive   macro    calls    in 
RSX-llM      directives      are      contained 
(LB: [1, IIRSXMAC.SML) .  The        .MCALL 

macros   available    to    a    program.      The 
all    the   maTos   used    in    the    program. 


you      use      system 


d  i  rect  i ves   by 

your  programs.   The  macros  tor  the 

in   tho   System   Macro    Library 

assembler   directive   makes  these 

.MCALL  arguments  are  the  names   of 

For  example: 


CALLING  DIRECTIVES  FROM  THE  SYSTEM  MACRO  LIBRARY 
AND  ISSUING  THEM. 


•MCALL   MRKT$S,WTSE$S 


Add 


tional  .MCALLs  or  code 


MRKTSS 
WTSS$S 


IH,»l,i2,,ERR 
#1 


;MARK  TIME  FOR  1  SECOND 

;WAIT  FOR  MARK  TIME  TO  COMPLETE 


Macro  names  consist  of  up  to  four  letters,  followed  by  a  dollar  sign 
($)  and,  optionally,  a  C  or  an  S.  The  optior.al  letter  or  its  absence 
specifies  which  of  three  possible  macro  ex aansions  the  programmer 
wants  to  use. 


1.4.1.1  $  Form  -  The  S  form  is  useful  for  a  directive  operation  tnu" 
is  to  be  issued  several  times  from  different  locations  in  a 
non-reentrant  program  segment.  The  $  form  is  most  useful  when  the 
directive  is  issued  several  times  with  varying  parameters  (one  or  more 
but  not  all  parameters  change),  or  in  a  reentrant  program  section  when 
a  directive  is  issued  sevc-ral  times  even  though  the  DPB  is  not 
modified.  This  form  produces  only  the  directive's  DPB,  and  must  be 
issued  from  a  data  section  of  the  program.  The  code  for  actually 
executing  a  directive  that  is  in  the  S  form  is  produced  by  a  special 
macro,  DIR$  (discussed  in  Section  1.4.2). 


Because  execution  of  the  directive  is  separate  from 
the  directive's  DPB: 


the   creation   of 


A  S  form  of  a  given  directive  needs  to 
( to  produce  its  DPB) . 


be   issued   only   once 


2.  A  DIRS  macro  associated  with  a  given  directive  can  be  issued 
several  timec  without  incurring  the  cost  of  generating  a  DPB 
each  time  it  is  issued. 

3.  It  is  easy  to  access  and  change  the  directive's  parameters  by 
labeling  the  start  of  the  DPB  and  using  the  offsets  defined 
by  the  directive. 

When  a  program  issues  the  ^  form  of  macro  call,  the  parameters 
required  for  DPB  construction  must  be  valid  expressions  for  MACRO-Il 
data  storage  instructions  (such  as  .bYTF,  .WORD,  and  .RADSO).  You  can 
alter  individual  parameters  in  the  DPB.  You  might  do  this  If  you  want 
to  use  the  directive  many  times  with  varying  parameters. 
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The  CTp$  macro  generates  an  RSX-1 IM  Executive  trap  using  a   predefined 
DPB: 

Macro  Call:   DIRS   adr,err 

adr  and  err  are  optional 

The  address  of  the  DPB.  (The  address,  if  specified,  must  be  a 
valid  source  address  for  a  MOV  instruction.)  If  this  address  is 
not  specified,  the  DPB  or  its  addresr  must  be  on  the  stacK. 

The  address  of  the  error  return  (jee  Section  1.4.3).  If  this 
error  return  is  not  specified,  an  error  simply  sets  the  carry  bit 
in  the  Processor  Status  Word. 

NOTE 

DIR$  is  not  a  $  form  macro,  and  does  not 
behave  as  one.  There  are  no  variations 
in  the  spelling  of  this  macro. 


adr 


err 


generates  the  following  code: 


MOV 

|DPB,-(SP) 

EMT 

377 

BCC 

.+6 

JSR 

PC, ERROR 

Since  the  $  form  of  a  directive  macro  does  not.  generate  any  executable 
code,  it  does  not  accept  an  error  address  argument. 


1.4.4   Symbolic  Offsets 

Most  system  directive  macro   calls   generate   local   symbolic  offsets 

describing   the   format   of   the   DPB.   The  symbols  are  unique  to  each 

directive,  and  each  is  assigned  an  index  value  corresponding  to  the 
offset  of  a  given  DPB  element. 

Because  the  offsets  are  defined  symbolically,  you  can  refer  to  or 
modify  DPB  elements  without  knowing  the  offset  values.  Symbolic 
offsets  also  eliminate  the  need  to  rewrite  programs  if  a  future 
release  of  RSX-1 IM  changes  a  DPB  specification. 

All  $  and  SC  forms  of  macros  that  generate  DBPs  longer  than  one  word 
generate  local  offsets.  All  informational  directives  (see  Section 
6.1.3),  including  the  $S  form,  generate  local  symbolic  offsets  for  the 
parameter  block  returned  as  well. 
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If  the  program  uses  either  the  $  or  $C  form  and  has  defined  the  symbol 
$$$GLB  (for  example  C$$GLB=0),  the  macro  generates  the  symbolic 
offsets  as  global  symbols  and  does  not  generate  the  DPB  itself.  The 
purpose  of  this  facility  is  to  en^Dle  the  use  of  a  DPB  defined  in  a 
different  module.  The  symbol  $$$GLB  has  no  effect  on  the  expansion  of 
$S  macros. 

When  using  symbolic  offsets,  you  should  use  the  $  form  of  directives. 


.BVTE 

23. ,5 

•  WORD 

1 

.WORD 

5 

.WORD 

2 

•  WORD 

MTRAP 

1.4.5   Examples  of  Macro  Calls 

The  examples  below  show  the  expansions  of   the   different   macro   call 
forms . 

1.   The  $  form  generates  a  DPB  only,  in  the  current  p-section. 

MRKT$     1,5, 2, MTRAP 

generates  the  following  code: 

"MARK-TIME"  DIC  i.  DPB  SIZE 
EVENT  FLAG  NUMBER 
TIME  INTERVAL  MAGNITUDE 
TIME  INTERVAL  UNIT  (SECONDS) 
AST  ENTRY  POINT 

The  $C  form  generates  in  p-section  $DPB$$  a  DPB,  and   in   the 
specified  section  the  code  to  issue  the  directive. 

MRKTSC    1, 5, 2,MTRAP,PR0G1, ERR 

generates  the  following  code; 

DEFINE  TEMPORARY  SYMBOL 

"MARK-TIME"  DIC  &  DPB  SIZE 

EVENT  FLAG  NUMBER 

TIME  INTERVAL  MAGNITUDE 

TIML  INTERVAL  UNIT  (SECONDS) 

AST  ENTRY  POINT  ADDRESS 

RETURN  TO  THE  ORIGINAL  PSECT 

PUSH  DPB  ADDRESS  ON  STACK 

TRAP  TO  THE  EXECUTIVE 

BRANCH  ON  DIRECTIVE  ACCEPTANCE 

ELSE,  CALL  ERROR  SERVICE  ROUTINE 

The  SS  form  generates  code  to  push  the  DPB  onto  the  stack  and 
to  issue  the  directive. 

MRKTSS  »1  ,  15, #2,R2,ERR 

generates  the  following  ~ode: 

PUSH  AST  ENTRY  POINT 

TIME  INTERVAL  UNIT  (SECONDS) 

TIME  INTERVAL  MAGNITUDE 

EVENT  FLAG  NUMBER 

AND  "MARK-TIME"  DIC  S,  DPB  SIZE 

ON  THE  STACK 

TRAP  TO  THE  EXECUTIVE 

BRANCH  ON  DIRECTIVE  ACCEPTANCE 

ELSE,  CALL  ERROR  SERVICE  ROUTINE 


.PSECT 

$DPB$$ 

$$C  =  . 

•  BYTE 

23.  ,5 

.WORD 

1 

.WORD 

5 

.WORD 

2 

.WORD 

MTRAP 

. PSECT 

PROGl 

MOV 

#$S$,-fSP) 

EMT 

377 

BCC 

.+6 

JSR 

PC, ERR 

MOV 

R2,-(SP) 

MOV 

»2,-fSP) 

MOV 

#5,-(SP) 

MOV 

#1,-(SP) 

MOV 

(PC)+,-(SP 

.BYTE 

23.  ,5 

EMT 

377 

BCC 

.+6 

JSR 

PC, ERR 
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The  DIRS  macro  issues  a  directive  that  has  a  predefined  DPB . 

DIRS      R1,(R3)         ;  DPB  ALREADY  DEFINED.   DPB  ADDRESS  IN  Rl, 

generates  the  following  code: 

;  PUSH  DPB  ADDRESS  ON  STACK 

;  TRAP  TO  THE  EXECUTIVE 

;  BRANCH  ON  DIRECTIVE  ACCEPTANCE 

;  ELSE,  CALL  ERROR  SERVICE  ROUTINE 


MOV 

«1,-(SP) 

EMT 

377 

BCC 

.+4 

JSR 

PC,  (R3) 

1.5   FORTRAN  SUBROUTINES 

RSX-llM/M-PLUS  provide  an  extensive   set 
perform  system  directive  opera':ions. 


The   directive   descriptions 
subroutine  calls,  as  well  as 


of   FORTRAN   subroutines   to 


th^ 


Chapter   5 
macro  calls. 


desc  r  ibe 


the 


FORTRAN 


The  FORTRAN  subroutines  fall  into  three  b<»sic  groups: 

•  Subroutines  based  on  the  Instrument  Society  of  America  (ISA) 
Standard  ISA  62.1  --  These  subroutines  are  included  in  the 
subroutine  descriptions  associated  with  the  macro  calls  (see 
Chapter  5) . 

•  Subroutines  designed  to  use  and  control  specific  process 
control  interface  devices  supplied  by  DIGITAL  and  supported  by 
the  RSX-1 IM/M-PLUS  operating  systems. 

•  Subroutines  for  performing  RSX-1 IM/M-PLUS  system  directive 
operations  --  In  general,  one  subroutine  is  available  for  each 
directive.  (Exceptions  are  the  Mark  Time  and  Run  directives. 
The  description  of  Mark  Time  incl  ides  both  TALL  MARK  and  CALL 
WAIT.  The  description  of  Run  includes  both  'ALL  RUN  and  CALL 
START. ) 


All  the  subroutines  described  in  this  manual  can  be  called  by  FORTRAN 
programs  compiled  by  either  the  FORTRAN  IV  or  FORTRAN  IV-PLUS 
compiler . 

These  subroutines  can  also  be  called  from  programs  written  in  the 
MACRO-11  assembly  language  by  using  PDP-11  FORTRAN  calling  sequence 
conventions.  These  conventions  are  described  in  the  IAS/RSX-1 1 
FORTRAN  IV  User's  Guide  and  in  the  FORTRAN  IV-PLUS  User's  GuTTe": 


1.5.1   Subroutine  Usage 

All  the  subroutines  described  in  this  manual  are  added  to  the  RSX-1 IM 
system  object  module  library  when  either  FORTRAN  compiler  is  generated 
for  RSX-1 IM.  You  call  these  subroutines  by  including  the  appropriate 
CALL  statement  in  the  FORTRAN  program.  When  the  program  is  linked  to 
form  a  task,  t-he  Task  Builder  first  checks  to  see  whether  each 
specified  subroutine  is  user  defined.  If  a  subroutine  is  not  user 
defined,  the  Task  Builder  automatically  searches  for  It  in  the  system 
object  module  library.  If  the  subroutine  is  found,  it  is  included  in 
the  linked  task. 
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1.5.1.1  Optional  Arguments  -  Many  of  the  subroutiti.^  i.  scribed  in 
this  manual  have  optional  arquments.  In  the  subroutine  descr.ptions 
associated  with  the  directives,  optional  arguments  are  designated  as 
such  by  being  enclosed  in  square  brackets  ([)).  An  argument  of  this 
kind  can  be  omitted  if  the  comma  that  immediately  follows  it  is 
retained.  If  the  argument  (or  string  of  optional  arguments)  is  last, 
it  can  simply  be  omitted,  and  no  comma  need  end  the  argument  list. 
For  example,  the  format  of  a  call  to  SUB  could  be  the  following: 

CALL  SUB  (AA, rSB) , [CO] ,DD( , f EE] I ,FF1 ] ) 

In  that  event,  you  may  omit  the  arguments  BB,  CC,  Et,  and  FF  in  one  of 
the  following  ways: 

•  CALL  SUB  (AA, , ,DD, ,) 

•  CALL  SUB  (AA, , , DD) 

In  some  cases,  a  subroutine  will  use  a  default  v.ilue  for  ^n 
unspecified  optional  argument.  Such  default  values  are  noted  in  each 
.subroutine  description  in  Chapter  S. 


1.5.1.2  Task  Names  -  In  FORTRAN  subroutines,  task  names  may  bt»  up  to 
six  characters  long.  Characters  permitted  in  a  task  name  are  the 
letters  A  through  2,  the  numerals  0  through  9,  and  the  special 
characters  dollar  sign  (S)  and  period  (.).  Task  names  are  stored  -is 
Radix-50  code,  which  permits  up  to  three  characters  from  the  set  above 
to  be  encoded  in  one  PDP-11  wori.  (Radix-50  is  described  in  detail  in 
the  lAS/RSX-I 1  FORTRAN  IV  User's  Guide  and  the  FORTRAN  IV-PLUS  User  's 
Guide.) 

FORTRAN  subroutine  calls  require  that  a  task  name  be  defined  as  a 
2-word  variable  or  array  that  contains  the  task  nam"  as  Radix-50  code. 
This  variable  may  be  any  of  the  following: 

•  REAL 

•  intf:ger*4 

•  An  integer*?  arra;  of  2  elements 

This  variable  may  be  defined  at  program  compilation  time  by  a  DATA 
statement,  which  gives  the  real  variable  an  initial  value  (a  Radix-50 
constant ) . 

For  example,  if  a  task  name  CCMFl  is  to  be  used  in  a  system  dir?ctivo 
call,  the  task  name  could  be  defined  and  used  as  follows: 

DATA  CCMF1/5RCCNF1/ 


CALL  RFQUES  ,CCMF1) 

A  program  may  define  ta^k  names  during  execution  by  using  the  IRAD50 
subroutine  or  the  RAD5n  function  as  described  in  the  I AS/RoX-1 1 
FORTRAN  IV  User's  Guide  or  the  FORTRAN  IV-PLUS  User's  Guide. 
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1.5.1.3  Integer  Arguments  -  All  the  subroutines  described  in  this 
manual  assume  that  integer  .  t  ts  are  INTEGER*2  type  arguments. 
Both  the  FORTRAN  IV  and  FORTRAN  V-.  .  JS  systems  normally  treat  an 
integer  variable  as  one  POP-  '  i  .-.orage  word,  provided  that  it 
is  within  the  range  -32768  to  -»  .:767.  However,  if  you  specify  •.  ■  •; 
option  switch  when  compiling  a  program,  ensure  that  all  Integer  attdy 
arguments  used  in  these  subroutines  are  explicitly  specified  as  type 
INTEGEP'2. 


1.5.1.4  GETADR  Subroutine  -  Some  subroutine  cal's  Include  an  argument 
described  as  an  integer  array.  The  integer  array  contairis  some  values 
that  are  the  addresses  of  other  variables  or  arrays.  Since  the 
FORTRAN  language  does  not  provide  a  means  of  assigning  such  an  address 
as  a  value,  you  must  use  the  GETADR  subroutine  described  helow. 

Calling  Sequence: 

CALL  GETADR (lpm,[argl],[arg2I,...[argn]^ 

ipm 

An  array  of  dimension  n. 

argl , . . .argn 

Arguments  whose  addresses  are  to  be  inserted  in  ipm.  Arguments 
are  inserted  In  the  order  specified.  If  a  null  argument  Is 
specified,  then  the  corresponding  entry  In  Ipm  Is  left  unchanged. 
When  the  argument  is  an  array  name,  the  address  of  the  first 
array  element  is  inserted  into  Ipm. 

Example : 

DIMENSION     rBUF(80) , I0SB{2) , rPARAM(6) 


CALL    GETADR      :  I  PARAW  (  1  i  ,  IB'JF  (  1  )  ) 

IPARAM(2) =8  0 

CALL  010  (IREAD, LUN,  ISFLAG,  rOSB,  IPARAM,  IDSW) 


In  this  example,   .ALL  GETADR  enables  you  to  specify  a   buffer   -xldress 
in  the  CALL  QIO  directi-'"  fsee  f.ectlon  5.3.44^. 


1.5.2   The  Subroutine  Calls 

Table  1-1  is  a  llsc  of  the  FORTRAN  subroutine  calls  ( snd  corresponding 
macro  calls)  associated  with  syst»»m  Hrei^tivs  (see  Chapter  5  for 
detailed  descriptions). 

For  some  directives,  notably  "^a  r  k  Time  (CALL  MARK),  both  th«,>  standard 
FORTRAN-IV  subroutine  call  and  the  ISA  standard  call  ar»*  provide<J. 
Other  directives,  however,  are  not  available  to  FORTRAN  tasks  (for 
example,  Specify  Floating  Point  Exception  AST  fyFPAS!  and  Specify  ;:ST 
Vector  Table  For  Task  fsVTK'Ii. 
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Table  l-I 
K'KTRAN  Suiiroutlnes  and  Corr 

■■,1  -^ 

• 

Directive 

Macro  Cal 1 

FORTRAN  5 

Abort  Task 

ABRTS 

CALL 

ABORT 

Alter  Priority 

ALTP$ 

CALL 

altpr: 

Aasiqn  LUN 

AL.UNS 

CALL 

ASNLIJN 

Attach  Region 

ATRG$ 

CALL 

atrg 

Cancel  Time  Based 
Initiation  Requests 

CRSOS 

CALL 

CANALL 

Cancel  Mark. 
Time  Requests 

CMKT$ 

CALL 

canmt 

Checkpoint  Common  Region 

CPCRS 

CALL 

CPCR 

Clear  Event  Flag 

CLEFS 

CAr.L 

CLREF 

Connect 

CNCTS 

CALL 

f'NCT 

Create  Address  Window 

CRAWS 

CALL 

CRAW 

Create  Group  Global 
Event  Flags 

CRGFS 

CALL 

CHGF 

Crf'.Tto  Rpt)  ion 

TRRG"!; 

CALt. 

CRRG 

Create  Virtual  Terminal 

CRVTS 

CALL 

crvt 

Declare  ^ ign  i  t  i'-an  t.  Event 

DECLSS 

CALL 

DECLAR 

Disable  AST  Recognition 

DSARSS 

CALL 

DSASTR 

Disable  Checkpointing 

DSCPSS 

CALL 

DISCKP 

Detach  Region 

DTRG5 

CALL 

DTRG 

Eliminate  Address  Window 

ELAWS 

CALL 

E  LAW 

F.liminate  Group  Global 
Event  Flags 

EI.GFS 

CALL 

ELGF 

Eliminate  Virtual  Terminal 

ELVTS 

CALL 

ELVT 

Emit  Status 

EMSTS 

CALL 

EM  ST 

Enable  AST  Recognition 

ENARSS 

CALL 

ENASTR 

Enable  Checkpo  i  nt  i  r.g 

ENCPSd 

CALL 

ENACKP 

Exit  If 

EXIFS 

CALt. 

EXITIF 

Exit  With  :tatuR 

EXSTS 

CALL 

EXST 

Extend  Task 

EXTK? 

CALL 

EXTTSK 

Get  Command  for 
Command  Interpreter 

GCCIS 

CALL 

GTCMCI 

(continued  on  next  pagp) 
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Table  1-1   (Cont.) 
FORTRAN  Subroutines  and  Corresponding  Macro  Calls 


Directive 

Macro  Call 

FORTRAN  Subroutine 

Get  Command 

GCII$ 

CALL  GETCII 

Interpreter  Information 

Get  LUN  Information 

GLUNS 

CALL  GETLUN 

Get  Mapping  Context 

GMCX$ 

CALL  GMCX 

Get  MCR  Command  Line 

GMCR$ 

CALL  GETMCR 

Get  Partition  Parameters 

GPRT$ 

CALL  GETPAR 

Get  Region  Parameters 

GREG$ 

CALL  GETREG 

Get  Sense  Switches 

GSSW$S 

CALL  READSW 
CALL  SSWTCH 

Get  Task  Parameters 

GTSK$ 

CALL  GETTSK 

Get  Time  Parameters 

GTIM$ 

CALL  GETTIM 

Inhibit  AST  Recognition 

IHAR$S 

CALL  INASTR 

Map  Address  Window 

MAP$ 

CALL  MAP 

Mark  Time 

MRKT$ 

CALL  MARK 

CALL  WAIT  (ISA  Standard 

call) 

Queue  I/O  Request 

QIO$ 

CALL  QIO 

Queue  I/O  Request  And  Wait 

QIOW$ 

CALL  WTQIO 

Read  All  Event  Flags 

RDAF$ 

K^XFS 

single,  local,   common, 
or   group-global   event 
flag  can  be  read   by   a 
FORTRAN  task) 

Read  Singla  Event:  Flag 

RDEF$ 

CALL  READEP 

Receive  By  Reference 

RREF$ 

CALL  RREF 

Receive  Data 

RCVD$ 

CALL  RECEIV 

Receive  Data  Or  Exit 

RCVX$ 

CA'.L  RECOEX 

Receive  Data  Or  Stop 

RCST$ 

CALL  RCST 

Remove  Affinity 

RMAF$S 

CALL  RMAr 

Request  and  Pass  Offspring 

RPOIS 

CALL  RPOI 

Informat ) on 

(continued  on  next  page) 
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Table  1-1   (Cont.) 
FORTRAN  Subroutines  ar d  Corresponding  Macro  Calls 


Di  rect  ive 

Macro  Call 

FORTRAN  Subroutine 

Request 

RQSTS 

CALL  REQUES 

Resume 

RSUM$ 

CALL  RESUME 

Run 

RUN$ 

CALL  RUN 

CALL  START  (I  "'.A 

Standard 

call) 

Send  By  Reference 

SREF$ 

CALL  SREF 

Send  Data 

SDAT$ 

CALL  SEND 

Send  Message 

SMSGS 

CALL  SMSG 

Send  Next  Command 

SNXC$ 

CALL  SNXC 

Send,  Request  And  Connect 

SDRC$ 

CALL  SDRC 

Set  Affinity 

STAF$ 

CALL  STAF 

£.  u  Command  Line  Interpreter 

SCLIS 

'"ALL  SCLI 

Send  Data  Request  an.1  Pass  OCB 

SDRr$ 

CALL  SDRP 

Set  Event  Flag 

SFTFS 

CALL  SETEF 

Set  System  Time 

STIMS 

CALL  SETTIM 

Spawn 

SPWNS 

CALL  SPAWN 

Specify  Power  Recovery  AST 

SFPA$ 

EXTERNAL  SUBNAM 
CALL  PWRUP  (SUBNAM) 

(to  establish  an    AST) 
CALL  PWRUP 

(to  remove  an  AST) 

Specify  Requested  Exit  AST 

SREA$ 
SREX$ 

CALL  SREA 
CALL  SREX 

Stop 

STOP$S 

CALL  STOP 

Stop  For  Logical  OR  Of 
Event  Flags 

S?  LOS 

CALL  STLOR 

Stop  For  Single  Event  Flag 

STSE$ 

CALL  STOPFR 

Suspend 

SPNDSS 

CALL  SUSPND 

Task  Exit 

EXITSS 

CALL  EKIT 

Unlock  Group  Global  Event 
Flags 

ULGF$S 

CALL  ULGF 

Unmap  Address  Window 

UMAPS 

CALL  UNMAP 

i 


(continued  on  next  page) 
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Table  1-1   (Cont.) 
FORTRAN  Subroutines  and  Corresponding  Macro  Calls 


Directive 

r  ■"  — 
Macro  Call 

FORTRAN  Subroutine 

Unstop 

USTP$ 

CALL 

USTP 

Variable  Receive  Data 

VRCD$ 

CALL 

VRCD 

Variable  Rec«»ive  Data  Or  Exit 

VRCX$ 

CALL 

VRCX 

Variable  Receive  Data  Or  Stop 

VRCS$ 

CALL 

VRCS 

Variable  Send  Data 

VSDA$ 

CALL 

VSDA 

Variable  Send,  Request 

VSRC$ 

CALL 

VSRC 

and  Connect 

Wait  For  Single  Event  Flag 

WTSE$ 

CALL 

WAITFR 

Wait  For  Logical  OR  Of 

WTLOS 

CALL 

WFLOR 

Event  Flags 

Wait  For  Significant:  Event 

WSIG$S 

CALL 

WFSNE 

NOTE 

The    following    directives    are    not 
available  as  FORTRAN  subroutines: 


Di  rect  ive 


Macro  Call 


AST  Service  Exit  ASTX$S 

Connect  To  Interrupt  Vector  CrNT$ 

Map  Supervisor  D-space  MSDS$ 

Move  to/from  Supervisor  MVTS$ 
or  User  I-  or  D-space 

Specify  Command  Arrival  AST  SCAA$ 

Specify  Floating  Point  SFPA$ 
Exception  AST 

Specify  Parity  Error  AST  SPEA$ 

Specify  Receive  By  Reference  AST   SRRA$ 

Specify  Receive  Data  AST  SRDAS 

Specify  SST  Vector  Table  For  SVDBS 
Debugging  Aid 

Specify  SST  Vector  Table  SVTK$ 
For  Tasks 

Supervisor  Call  SCAL$S 
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1.5.3   Error  Conditions 

Each  subroutine  rail  includes  an  optional  arqument  that  specifies  the 
Integer  to  receive  the  Directive  Status  Word  (Ids).  When  you  specify 
this  argument,  the  subroutine  returns  a  value  that  Indicates  whether 
the  directive  operation  succeeded  or  failed.  If  the  directive  failed, 
the  value  Indicates  the  reason  for  the  failure.  The  possible  values 
are  the  same  as  those  returned  to  the  Directive  Status  Word  (DSW)  In 
MACRO-11  programs  (see  Appendix  B) ,  except  for  the  two  ISA  calls,  CALL 
WAIT  and  CALL  START.  The  ISA  calls  have  positive  numeric  error  codes 
(see  Sections  5.3.41  and  5.3.5'7). 

In  addition,  two  types  of  error  are  reported  by  means  of  the  FORTRAN 
Object  Time  System  (OTS)  diagnostic  messages.  Both  of  these  errors 
result  In  the  termination  of  the  task.   The  error  conditions  are: 

•  DIRECTIVE:       MISSING    ARGUMENT(S) 

This  message  indicates  that  at  least  one  necessary  argument 
was  missing  from  a  call  to  a  system  directive  subroutine  (OTS 
error  number  100) . 

•  DIRECTIVE:        INVALID    EVENT    FLAG    NUMBER 

This  message  Indicates  that  an  event  flag  number  in  a  call  to 
STLOR  (Stop  for  Logical  OR  of  Event  Flags),  or  WFLOR  (Walt  For 
Logical  OR  Of  Event  Flags)  was  not  in  the  range  I  to  96  (OTS 
error  number  101). 


1.5.4   AST  Service  Routines 

The  following  FORTRAN  callable  routines  provide  support   for   ASTs   in 
FORTRAN  programs: 


CALL 

CNCT 

CALL 

CRVT 

CALL 

PWRUP 

CALL 

SDRC 

CALL 

SPAWN 

CALL 

SREA 

CALL 

SREX 

Use  great  caution  when  coding  an  f\ST  routine  in  FORTRAN.  The 
following  types  of  FORTRAN  operations  may  not  be  performed  at  AST 
state : 

•  FORTRAN   I/O   of   any   kind   (including   ENCODE    and    DECODE 
statements  and  internal  file  I/O) 

FORTRAN  I/O  is  not  reentrant,  therefore  the  information  in 
the  impure  data  area  may  be  destroyed. 

•  Floating-point    operations 

The  floating-point  processor's  context  is  not  saved  while 
in  AST  state.  Since  the  scientific  subroutines  use 
floating-point  operations,  they  may  not  be  called  at  AST 
state . 
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Traceback  information  in  the  generated  code 

Use  of  traceback  corrupts  the  error  recovery  in  the  FORTRAN 
run  time  library.  Any  FORTRAN  modules  that  will  be  called 
at  AST  state  must  be  compiled  without  traceback.  See  the 
FORTRAN  IV  or  FORTRAN-/.'  Mser's  Guide  for  more  information. 

Virtual  array  operations 

Use  of  virtual  arrays  at  AST  state  remaps  the  current  array 
such  that  any  operations  at  non-AST  state  will  not  be 
executed  correctly. 

Subprograms  may  not   be   shared   between   AST   processing   and 
normal  task  procesaing. 

EXIT  or  STOP  statements  with  files  open 

FORTRAN  flushes  the  i:<»sk's  buffers,  which  could  be  in  an 
intermediate  state.  Therefore,  data  might  be  lost  if  any 
output  files  are  open  when  the  FXIT  or  STOP  is  executed. 


You  can  EXIT  oi 
open . 


?r  AST  state  if  no   output   files   are 


Since  the  messag»»  put  out  by  STOP  uses  a  different 
mechanism  from  the  normal  FORTRAN  I/O  routines,  the  act  of 
putting  out  this  message  does  not  corrupt  impjre  data  in 
the  run  time  system.  Therefore,  /ou  can  issue  a  STOP 
statement  at  AST  state  u.iless  there  are  output  files  open. 

Note  also  the  following: 

•  Any  execution  time  error  at  AST  state  will  corrupt  the 
prog  ram . 

•  Use  extreme  care  if  the  FORTRAN  task  is  overlayecl.  Both  the 
interface  routine  and  the  actual  code  of  the  FORTRAN  AST 
routine  must  be  located  in  the  root  segment.  Any  routines 
that  are  called  at  AST  state  must  also  be  in  the  root  segment. 


1.6   TASK  STATES 

Many  system  directives  cause  a  task   to   change   from   one   state   to 

another.    There  are  two  basic  task  states  in  RSX-1 IM/M-PLUS :   dormant 

and  active.  The  active  state  has  three  substates:  ready-to-run, 
blocked,  and  stopped. 

The  Executive  recognizes  the  existence  of  a  task  only  after  it  has 
been  successfully  installed  and  has  an  entry  in  the  System  Task 
Directory  (STD) .  (Task  installation  is  the  process  whereby  a  task  is 
made  known  to  the  system;  see  the  RSX-1 IM/M-PLUS  MCR  Operat  ions 
Manual . )  Once  a  task  has  been  installed,  i  t  i  s  either  dormant  or 
active.   Thes«  states  are  defined  as  follows: 

•  Dormant  --  Immediately  following  the  processing  of  an  Install 
command  by  the  Monitor  Console  Routine,  a  task  is  known  to  the 
system,  but  is  dormant.  A  dormant  task  has  an  entry  in  the 
STD,  but  no  request  has  been  made  to  activate  it. 
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•  Active  --  A  task  Is  active  from  the  time  it  is  requested  until 
the  time  it  exits.  Requesting  a  task  means  issuing  the  ROSTS, 
RUNS,  SPWNS,  SDRCS,  VSRCS,  RPOIS,  or  SDRPS  macro,  or  an  KCR 
Run  command.  An  active  task  is  eligible  for  scheduling, 
whereas  a  dormant  task  is  not. 

The  three  substates  of  an  active  task  are  as  follows: 

a.  Ready-to-run  --  A  ready-to-run  task  competes  with  other 
tasks  for  CPU  time  on  the  basis  of  priority.  The  highest 
priority  ready-to-run  task  obtains  CPU  time  and  thus 
becomes  the  current  task. 

b.  Blocked  --  A  blocked  task  is  unable  to  compete  for  CPU 
time  for  synchronization  reasons  or  because  a  needed 
resource  is  not  available.  Task  priority  effectively 
remains  unchanged,  allowing  the  task  to  compete  for  memory 
space. 

c.  Stopped  --  A  stopped  t?3k  Is  unable  to  compete  for  CPU 
time  because  of  pending  I/O  completion,  event  flag(s)  not 
set,  or  because  the  task  stopped  itself.  When  stopped,  a 
task's  priority  effectively  drops  to  zero  and  the  task  can 
be  cneckpo  inter!  by  any  other  task,  regardless  of  that 
task's  priority.  If  an  AST  occurs  for  the  stopped  task, 
Its  normal  task  priority  is  restored  only  for  th»»  duration 
of  the  AST  routine  execution;  once  the  AST  is  completed, 
task  priority  returns  to  zero. 


1.6.1   T^sk  State  Transitions 

Dormant  to  Active  -  The  following  commands   or   directives   cause   the 
Executive  to  activate  a  dormant  task: 

•  A  RUNS  directive 

•  A  RQSTS  directive 

•  A  SPWNS  directive 

•  A  SDRCS  directive 

•  A  VSRCS  d'-3Ctive 

•  A  RPOIS  directive 

•  A  SDRPS  directive 

•  An  MCR  or  DCL  Run  command 

Ready-to-Run  to  Blocked   -   The   following   events   cause   an   active, 
ready-to-run  task  to  become  blocked: 

•  A  SPNDS  directive 

•  A-  unsatisfied  Wait  For  condition 

•  Checkpointing  of  a  task  out  of  memory  by  the  Executive 
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Ready-to-Run  to  Stopped   -   The   following   events   cause   an   active, 
ready-to-rim  task  to  become  stopped; 

•  A  STOPSS  directive  is  executed,  or  an  RCSTS,  SDRPS,  GCCIS,  or 
VRCS$  directive  is  issued  when  no  data  packet  is  available. 

•  An  unsatisfied  Stop  For  condition. 

•  An  unsatisfied  Walt  For  condition  while  the  task  has 
outstanding  buffered  I/O.l 

Blocked  to  Ready-to-Run  -  The  following  events  return  a   blocked   task 
to  the  ready-to-run  state: 

•  A  RSUMS  directive  issued  by  another  task 

•  An  MCR  Resume  command  or  a  DCL  Continue  command 

•  A  Wa i t  For  condition  is  satisfied 

•  The  Executive  reads  a  checkpolnted  task  into  memory 

Stopped  to  Ready-to-Run  -  The  following  events  return  a   stopped   taak 
to  the  ready-to-run  state,  depending  upon  how  the  task  became  stopped: 

•  A  task  stopped  by  the  STOPS,  RCSTS,  ot  VRCS$  directive  becomes 
unstopped  by  USTPS  directive  execution,  or  an  MfR  Unstop 
command  or  DCL  START  command. 

•  A  Wait  For  condition  is  satlslfied  for  a  task  with  outstanding 

buffpred  I/O. 

•  A  task  stopped  for  a  event  flag  (or  flags)  becomes  unstopped 
when  the  specified  event  flag  (or  flags)  becomes  (or  become) 
sp  t . 

Active  to  Dormant  -  The  following   events   cau.ie   an   active   task   to 
becoiTie  dormant: 

•  An  EXITSS,  EXIFS,  RCVXS,  or  VRCXS  directive,  or  a  RREFC  or 
GCCIS  directive  that  specifies  the  exit  option 

•  An  ABRTS  directive 

•  An  MCR  or  DCL  Abort  command 

•  A  Synchronous  System  Trap  fSST)  for  which  a  task  has  not 
specified  a  service  routine 

Blocked  to  Stopped  -  The  following  event  causes  a  task  that  is  blocked 
due  to  an  unsatisfied  Wait  For  condition  to  become  stopped: 

•  The  task  initiates  buffered  I/O  at  AST  state  and  then  oxits 
from  AST  state. 


1.  Only  in  systems  that  support  tho  checkpointing  of  tasks  during 
buffered  I/O.  An  I/O  request  can  be  buffered  only  when  the  task  is 
checkpointable  and  the  region  that  I/O  is  being  done  to/from  is 
checkpointable . 
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Stopped  to  Blocked  -  The  following  event  causes  a  task  that  is  stopped 
due  to  an  unsatisfied  Wait  For  condition  and  outstanding  buffered  I/O 
to  return  to  a  blocked  state: 


Completion  of  all  outstanding  buffered  I/O 


1.6.2   Removing  an  Installed  Task 


You  remove  an  installed  task  from  the  system  by  issuing  the  MCR  or  DCL 
Remove  command  from  a  privileged  terminal.  Refer  to  the 
RSX-llM/llM-PLUS  MCR  Operations  Manual  or  the  RSX-1 IM/M-PLUS  Command 
Language  Reference  Manual . 


1.7   THE  GENERAL  INFORMATION  DIRECTIVE 

Some  of  DIGITAL'S  software  modules  use  the  General  Information 
Directive  to  obtain  information  from  Executive  data  structures  withouc 
being  directly  mapped  to  the  Executive.  Since  this  directive  may 
change  from  reloase  to  release  of  RSX-llM-PLUS,  it  is  specifically  not 
documented  in  this  manual.  However,  advanced  users  desiring  to  use 
this  directive  can  refer  to  the  Executive  module  [ 11, lOJDRGIN.MAC  and 
macro  GIN$  in  the  Executive  macro  library.  Although  the  directive  may 
operate  in  the  same  manner  in  future  releases,  its  operation  Is 
specifically  not  guaranteed,  and  users  are  cautioned  accordingly. 


1.8   DIRECTIVE  RESTRICTIONS  FOR  NONPRIVILEGED  TASKS 

Nonpr ivileged  tasks  cannot  issue  certain  Executive  directives,   except 
as  listed  below: 


Directive 


Macro  Call 


Conments 


Abort  Task 


ABRT$ 


In  systems  that  support 
multiuser  protection,  a 
nonpr ivileged  task  can  only 
abort  tasks  with  the  same 
TI:  as  the  task  issuing  the 
directive. 


Alter  Priority 


ALTP$ 


Cancel  Time  Based 
Initiation  Requests 


CSROS 


In  systems  that  support 
multiuser  protection,  a 
nonpr ivileged  task  can  only 
alter  its  own  priority  to 
values  less  than  or  equal  to 
the  task's  installed 
pr  ior  i  ty . 


Cannot    be    issued    by 


nonpr ivileged     task 
systems      that 
multiuser  protection 
for   tasks  with  the  : 
as  the  issuing  task. 


a 

in 

support 

except 

same  TI: 
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Directive 


Macro  Call 


CoBfflents 


Connect  To 
Vector 


interrupt 


Set  Command  Line 
Interpreter 


CINT$ 


SCLI$ 


Cannot  be  issued  by  a 
nonpr ivileged  task  in  mapped 
systems. 

Cannot  be  issued  by  a 
nonpr ivileged  task  under  any 
circumstances . 


1.9   RSX-llM-PLUS 

HSX-llM-PLUS  supports  multiprocessor  PDP-11  syst^jm  configurations  and 
provides  additional  Executive  services.  Sxecutive  services  include 
virtual  terminal  support,  supervisor-mode  library  support,  CPU/UNIBUS 
affinity,  parity  error  AST  routine  support,  and  Executive-level 
dispatching . 
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CHAPTER  2 
SIGNIFICANT  EVENTS,  SYSTEM  TRAPS,  AND  STOP-BIT  SYNCHRONIZATION 


This  chapter  introduces  the  concept  of  significant  events  and 
describes  the  ways  in  which  your  code  can  make  use  of  event  flags, 
synchronous  and  asynchronous  system  traps,  and  stop-bit 
synchronization. 


2.1   SIGNIFICANT  EVENTS 

A  significant  event  is  a  change   in   system   status   that  causes   the 

Executive   to   reevaluate   the   eligibility  of  all  active  tasks  to  run 

(For  some  significant  events,  specifically  those  in  which  the   current 

task  becomes  ineligible  to  run,  only  those  tasks  of  lower  priority  are 

examined.)  A  significant  event  is  usually  caused  (either  directly  or 
indirectly)  by  a  system  directive  issued  from  within  a  task. 
Significant  events  include  the  following: 

•  An  I/O  completion 

•  A  task  exit 

•  The  execution  of  a  Send  Data  directive  (see  Section  5.3.(^1) 

•  Tie  execution  of  a  Send  Data,  Request  and  Pass  OCB  directive 
(see  Section  5.3.63) 

•  The  execution  of  a  Send,  Request,  and  Connect  directive  (see 
Section  5. 3. 62) 

•  The  execution  of  a  Send  By  Reference  or  a  Receive  By  Reference 
directive  (see  Sections  5.3.74  and  5.3.55) 

•  The  execution  of  an  Alter  Priority  directive  (see  Section 
5.  3. 2) 

•  The  removal  of  an  entry  from  the  clock  queue  (for  instance, 
resulting  from  the  execution  of  a  Mark  Time  directive  or  the 
issuance  of  a  rescheduling  request) 

•  The  execution  of  a  Declare  Significant  Event  directive  (see 
Section  5 . 3.  16) 

•  The  execution  of  the  round-robin  scheduling  algorithm  at  the 
end  of  a  round-robin  scheduling  interval 

•  The  execution  of  an  Exit,  an  Exit  With  Status,  or  an  Emit 
Status  directive 
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2. 2   EVENT  FLAGS 

Event  flags  are  a  means  by  which  tasks  recognize  specific  events. 
(Tasks  also  use  Asynchronous  System  Traps  (ASTs)  to  recognize  specific 
events.  S^e  Section  2.3.3.)  In  requesting  a  system  operation  (such  as 
an  I/O  transfer),  a  task  may  associate  an  event  flag  with  the 
completion  of  the  operation.  When  the  event  occurs,  the  Executive 
sets  the  specified  flag.  Several  examples  later  in  this  section 
describe  how  tasks  can  use  event  flags  to  coordinate  task  execution. 

Ninety-six  event  flags  are  available  to  enable  tasks  to  distinguish 
one  event  from  another.  Each  event  flag  has  a  corresponding  unique 
Event  Flag  Number  (EFN)  Numbers  1  through  32  form  a  group  of  flags 
that  are  unique  to  each  task  and  are  set  or  cleared  as  a  result  of 
that  task's  operation.  Numbers  13  through  64  form  a  second  group  of 
flags  that  are  common  to  all  tasks,  hence  their  name  "common  flags." 
Common  flags  may  be  set  or  cleared  as  a  result  of  any  task's 
operation.  The  last  eight  flags  in  each  group,  local  flags  (25-32) 
and  common  flags  (57-54),  are  reserved  for  use  by  the  system.  Numbers 
65  through  96  form  the  third  group  of  flags,  known  as  "group-global 
event  flags."  You  can  use  th'>se  flags  In  any  application  where  common 
event  flags  can  be  used;  however,  only  tasks  running  under  UICs 
containing  the  group  code  specified  when  the  group-global  event  flags 
were  created  can  use  them.  Four  directives  (Create  Group  Global  Event 
Flags,  Eliminate  Group  Global  Event  Flags,  Unlock  Group  Global  Event 
Flags,  and  Read  Extended  Event  Flags)  provide  the  Executl'-e  support 
for  Implementing  group-global  event  flags. 

Tasks  can  use  the  common  or  group  global  flags  for  Intertask 
communication  or  their  own  lojal  event  flags  Internally.  They  can 
set,  clear,  and  test  event  flags  by  using  Set  Event  Flag  (SETF$), 
Clear  Event  Flag  (CLEFS),  and  Read  All  Event  Flags  (RDAFS)  directives. 
(The  Read  All  Event  Flags  directive  will  not  return  the  group-global 
event  flags.  When  these  flags  are  in  use,  read  all  event  flags  using 
the  Read  Extended  Event  Flags  (RDXFS)  directive.) 

Take  great  care  when  setting  or  clearing  event  flags,  especially 
common  and  group  global  fla^^s.  Erroneous  or  multiple  setting  and 
clearing  of  event  flags  can  result  in  obscure  software  faults.  A 
typical  application  program  can  be  written  without  explicitly 
accessing  or  modifying  event  flags,  since  many  of  the  directives  can 
Implicitly  perform  these  functions.  The  Send  Data  (SDATS) ,  Mark  Time 
(MRKTS),  and  the  I/O  operations  directives  can  all  Implicitly  alter  an 
event  flag . 

Examples  1  and  2  below  illustrate  the  use  of  common  event  flags 
(33-64)  to  synchronize  task  execution.  Examples  3  and  4  illustrate 
the  use  of  local  flags  (1-32). 

Example  1 

Task  B  clears  common  event  flag  35  and  then  blocks  Itself  by 
issuing  a  Wait  For  directive  that  specifies  common  event  flag  35. 

Subsequently  another  task,  Task  A,  specifies  event  flag  35  in  a 
Set  Event  Flag  directive  to  Inform  Task  B  that  It  may  proceed. 
Task  A  then  Issues  a  Declare  Significant  Event  directive  to 
ensure  that  the  Executive  will  schedule  Task  B. 

Example  2 

In  order  to  synchronize  the  transmission  of  data  between  Tasks  A 
and  B,  Task  A  specifies  Task  B  and  common  event  flag  42  In  a  Send 
Data  directive. 
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Task  B  has  specified  flag  42  In  a  Wait  For  directive.  When  Task 
A's  Send  Data  directive  has  caused  the  Executive  to  set  flag  42 
and  to  cause  a  significant  event,  Task  B  proceeds  and  Issues  a 
Receive  Data  directive  because  its  Wait  For  condition  has  been 
sat  isf led  . 


Example  3 


A  task  contains  a  Queue  I/O  Request  directive  and  an  associated 
Wait  For  directive;  both  directives  specify  the  same  local  event 
flag.  When  the  task  queues  Its  I/O  request,  the  Executive  clears 
the  local  flag.  If  the  requested  I/O  Is  Incomplete  when  the  task 
Issues  the  Wait  For  directive,  the  Executive  blocks  the  task. 

When  the  requested  I/O  has  been  completed,  the  Executive  sets  the 
local  flag  and  causes  a  significant  event.  The  task  then  resumes 
its  execution  at  the  instruction  that  follows  the  Walt  For 
directive.  Using  the  local  event  flag  in  this  manner  ensures 
that  the  task  does  not  n.anipulate  Incoming  dat-T  until  the 
transfer  is  complete. 

Example  4 

A  task  specifies  the  same  local  event  flag  in  a  Mark  Time  and  an 
associated  Wait  For  directive.  Wlien  the  Mark  Time  'iirective  is 
Issued,  the  Executive  first  clears  the  local  flag  and 
subsequently  sets  it  when  the  indicated  time  interval  has 
elapsed . 

If  the  task  issues  the  Wait  For  directive  before  the  local  flag 
has  been  set,  the  Executive  blocks  the  task,  which  resumes  when 
the  flag  Is  set  at  the  end  of  the  proper  time  Interval.  If  the 
flag  has  been  set  first,  the  directive  is  a  no-op  and  the  task  is 
not  blocked . 

Specifying  an  event  flag  does  not  mean  that  a  Wait  For  directive  must 
be  issued.  Event  flag  testing  can  be  performed  at  any  time.  The 
purpose  of  a  Walt  For  directive  is  to  stop  task  execution  until  an 
Indicated  event  occurs.  Hence,  it  is  not  necessary  to  Issue  a  Walt 
For  directive  immediately  following  a  Queue  I/O  Request  directive  or  a 
Mark  Time  directive. 

If  a  task  issues  a  Wait  For  directive  that  specifies  an  event  f  1  :.g 
that  is  already  set,  the  blockinc,  condition  is  Immediately  satisfied 
and  the  Executive  immediately  returns  control  to  the  task. 

Tasks  can  issue  Stop  For  directives  instead  of  Walt  For  directives. 
When  this  is  done,  an  event  flag  condition  not  satisfied  will  result 
in  the  tajk's  being  stopptfd  instead  of  being  blocked  until  the  event 
flag(s)  is  set.  A  task  that  is  blocked  still  competes  for  memory 
resources  at  <ts  running  priority.  A  task  tfiat  is  stopped  competes 
for  memory  resources  at  priority  0. 

The  simplest  way  to  test  a  singl'^  event  flag  is  to  issue  the  directive 
CLEFS  or  SETFS.  Both  these  directives  can  cause  the  following  return 
codes : 

IS.CLR  -  Flag  was  previously  clear 

IS. SET  -  Flag  was  previji^sly  set 


2-3 


SIGNIFICANT  EVENTS,  SYSTEM  TRAPS,  AND  STOP-BIT  SYNCHRONIZATION 

For  example,  if  a  set  common  event  flaq  Indicates  the  completion  of  an 
operation,  a  task  can  issue  the  CLEFS  directive  both  to  read  the  event 
flag  and  simultaneously  to  reset  it  for  the  next  operation.  If  the 
event  flag  was  previously  clear  (the  current  operation  was 
incomplete),  the  flag  remains  clear. 


2. 3   SYSTEM  TRAPS 

System  traps  are  transfers  of  control  (also  called  software 
interrupts)  that  provide  tasks  with  a  means  of  monitoring  and  reacting 
to  events.  The  Executive  Initiates  system  traps  when  certain  events 
occur.  The  trap  transfers  control  to  the  task  associated  with  the 
event  and  gives  the  task  the  opportunity  to  service  the  event  by 
entering  a  user-written  routine. 

There  are  two  kinds  of  system  trap?: 

•  Synchronous  System  Traps  (SSTs)  --  SSTs  detect  events  directly 
associated  with  the  execution  of  program  instructions.  They 
are  synchronous  because  thty  always  recur  at  the  same  point  In 
the  program  when  trap-ca  sing  instructions  occur.  For 
example,  an  illegal  instruction  causes  an  5ST. 

•  Asynchronous  System  Traps  (ASTs)  --  AT-Ts  detect  events  that 
occur  asynchronously  to  the  task's  execution.  That  Is,  the 
task  has  no  direct  control  over  the  precise  time  that  the 
event  --  and  therefore  the  trap  --  may  occur.  The  completion 
of  an  I/O  transfer  jnay  cause  an  AST  to  occur,  for  example. 

A  task  that  uses  the  system  trap  facility  Issues  system  directives 
that  establish  entry  points  for  user-written  service  routines.  Entry 
points  for  SSTs  are  specified  in  a  single  table.  AST  entry  points  are 
set  by  Individual  directives  for  each  kind  of  AST.  When  a  trap 
condition  occurs,  the  task  automatically  enters  the  appropriate 
routine  (If  Its  entry  point  has  been  specified). 


2. 3. 1   SynchrDnous  Systea  Traps  (SSTs) 
SSTs  can  detect  the  execution  of: 

•  Illegal  instructions 

•  Instructions  with  invalid  addresses 

•  Trap  instructions  (TRAP,  EMT,  lOT,  OPT) 

•  FIS  floating-point  exceptions  (PDP-ll/40  only) 

The  user  can  set  up  an  SST  vector  table,  containing  one  entry  ?•:•  r  :'ST 
type.  Each  antry  is  the  address  of  an  SST  routine  that  services  a 
particular  type  of  SST  fa  routine  that  services  illegal  instructions, 
for  example) .  When  an  SST  occurs,  the  Executive  transfers  control  to 
the  routine  for  that  type  of  SST.  If  a  corresponding  routine  Is  not 
specified  in  the  table,  the  task  is  aborted.  The  SST  routine  enables 
the  user  to  process  the  failure  and  then  return  to  the  interrupted 
code.  Note  that  if  a  debugging  aid  and  the  user's  task  both  h^ive  an 
SST  vector  enabled  for  a  given  condition,  the  debugging  aid  vector  is 
referenced  first  to  determine  the  service  routine  address. 
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SST  routines  must  always  be  reentrant  if  there  is  a  possibility  that 
an  SST  can  occur  within  the  SST  routine  Itself.  Although  the 
Executive  Initiates  SSTs ,  the  execution  of  the  related  service 
routines  Is  indistinguishable  from  the  task's  normal  execution.  An 
AST  or  another  SST  can  therefore  Interrupt  an  SST  routine. 


2.3.2   SST  Service  Routines 

The  Executive  Initiates  SST  service  routines  by  pushing  the  task's 
Processor  Status  (PS),  Program  Counter  (PC),  and  trap-specific 
parameters  onto  the  task's  stack.  After  removing  the  trap-specific 
parameters,  the  service  routine  returns  control  to  the  task  by  issuin<j 
an  RTI  or  RTT  instruction.  Note  that  the  task's  general  purpose 
registers  R0-R5  and  SP  are  not  saved.  If  the  SST  routine  makes  use  of 
them,  it  must  save  and  restore  them  itself. 

To  the  Executive,  SST  routine  execution  Is  Indistinguishable  from 
normal  task  execution,  so  that  all  directive  services  are  available  to 
an  SST  loutine.  An  SST  routine  can  remove  the  Interrupted  PS  and  PC 
from  the  stack  and  transfer  control  anywhere  in  the  task;  the  routine 
does  not  have  to  return  control  to  the  point  of  Interruption.  Note 
that  any  operations  performed  by  the  routine  (such  as  the  modification 
of  registers  or  the  DSW,  or  the  setting  or  clearing  of  event  flags) 
remain  In  effect  when  the  routine  eventually  returns  control  to  the 
task . 

A  trap  vector  table  within  the  task  contains  all  the  service  rauline 
entry  points.  You  can  specify  the  SST  vector  table  by  means  of  the 
Specify  SST  Vector  Table  For  Task  directive  or  the  Specify  SST  Vector 
For  Debugging  Aid  directive.  The  trap  vector  table  has  the  followlmj 
format : 


Word 

0 


Of fest 
S.COAD 


Assoc  lated 
Vector 


Trap 

Odd  or  nonexistent  memory  error 
(Also,  on  some  PDP-11  processors  -- 
for  example,  PDP  11/45  --  an  illegal 
Instruction  traps  here  rather  than 
t  h  r  o  ug  h  wo  r  d  0  4). 


1 

S.CSGF 

2^.0 

2 

S.CBPT 

14 

3 

S.CIOT 

20 

4 

S.CILI 

10 

5 

S.CEM7 

3  0 

6 

S.CTRP 

34 

7 

S.CFLT 

244 

Memory  protect  violation 

T-bit  trap  or   execution   of 
Inst  rue 1 1  en 


RPT 


Execution  of  an  lOT  instru"tlon 

Execution    of    a    reserved     i  nr>r  r  uc  t  1  oi, 

Execution    of    i     non-RSX     KMT 
i  nst  ruct  ion 

Execution  of  ^    TRAP  i  n.st  r  uc  t  1  on 

Synchronous  float  ing-ixi  i  nt  excnption 
(PDP-1 1/40  only) 
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A  zero  appearing  in  the  table  means  that  no  entry  point  is  specified. 
An  odd  address  in  the  table  causes  an  SST  to  occur  when  another  SST 
tries  to  use  that  particular  address  as  an  entry  point.  It  an  SST 
occurs  and  an  associated  entry  point  is  not  specified  in  the  table, 
the  Executive  aborts  the  task. 

An  even  vector  entry  causes  the  SST  routina  to  be  executed  in  tho  same 
mode  (either  user  or  supervisor)  that  the  processor  was  in  when  the 
SST  vector  was  specified.  An  odd  vector  entry  causes  the  SST  routine 
to  be  execu'-ed  in  the  other  mode.  For  example,  if  the  processor  was 
in  supervisor  mode  and  the  vector  entry  was  odd,  the  SST  routine  is 
executed  in  user  mode. 

Depending  on  the  reason  for  the  SST,  the  task's  stack  may  also  contain 
additional  information,  as  follows: 

Memory  protect  violation  (complete  stack) 

SP+10  —  PS 

SP+06  —  PC 

SP+04  —  Memory  protect  status  register  (SRO)l 

SP+02  —  Virtual  PC  ■- t  the  faulting  instruction  (SR2)1 

SP+00  --  Instructio'i  backup  rer  ister  (SRl)l 

TRAP  instruction  or  EMI  --rhpr  than  377  (and  376  in   the   case   of 
unmaoped  tasks  and  mapped  privileged  tasks)  (complete  stack) 

SP+04   --   PS 
SP+02   ---   PC 

SP+00   --   Instruction  operand  (low-order  byte)  multiplied  by   2, 
non-sign-extended 

All  items  except  the  PS  and  PC  must  be  removed  from  the  stack  before 
the  SST  service  routine  exits. 


2.3.3  Asynchronous  System  Traps  (ASTs) 

The  primary  purpose  of  an  AbT  is  to  inform  the  task  that  a  certain 
event  has  occurred-for  example,  the  completion  of  an  I/O  operation. 
As  soon  as  the  task  has  serviced  the  event,  it  can  return  to  the 
interrupted  code. 

Some  directives  can  specify  both  an  event  flag  and  an  AST;  »••*  th  these 
directives,  ASTs  can  be  used  as  an  alternative  to  event  flags  or  the 
two  can  be  used  together.  Therefore,  you  can  specify  the  same  AST 
routine  for  several  directives,  each  with  a  different  event  flag. 
Thus,  when  the  Executive  passes  control  to  the  AST  routine,  the  event 
flag  can  determine  the  action  required. 

AST  service  routines  must  save  and  restore  all  registers  used.  If  the 
registers  are  not  restored  a^ter  an  AST  has  occurred,  the  task's 
subsequent  e<ecution  may  be  unpredictable. 

Although  not  able  to  distinguish  execution  of  an  SST  routine  from  task 
execution,  the  Executive  is  aware  that  a  task  is  executing  an  AST 
routine.  An  AST  routine  can  be  interrupted  by  an  SST  routine,  but  not 
by  another  AST  routine. 


1.  For  details  of  SRO,  SRI,  and  SR2,  see  the   section   on   the   memory 
management  unit  in  the  appropriate  PDP-11  processor  handbook. 
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The  following  notes  describe  general  characteristics  and  uses  of  ASTs : 

•  If  an  AST  occurs  while  the  related  task  is  executing,  the  t.isk 
is  Interrupted  so  that  the  AST  service  routine  can  be 
executed . 

•  li  an  AST  occurs  while  another  AST  is  being  processed,  the 
Executive  queues  the  latent  AST  ( Fi rst-In-Fi r dt-Out  or  FIFO). 
The  task  then  processes  the  next  AST  in  the  queue  when  the 
current  AST  service  is  complete  (unless  AST  recognition  was 
disabled  by  the  AST  service  routine). 

•  If  a  task  is  suspended  or  stopped  when  an  associated  AST 
occurs,  the  task  remains  suspended  or  stopped  after  the  AST 
routine  has  been  executed,  unless  i^  is  explicitly  resumed  or 
unstopped  either  by  the  AST  service  routine  itself,  or  by 
another  task  (thR  NCR  and  DCL  ReJume  or  UNSTOP  command,  for 
example) . 

•  If  an  AST  occurs  while  the  related  task  is  waiting  (or 
stopped)  for  an  event  flag  to  be  set  (a  Wait  For  (Stop  For) 
directive),  the  task  continues  to  wait  after  execution  of  the 
AST  service  routine  unless  the  event  flag  is  set  upon  AST 
exit . 

•  If  an  AST  occurs  for  a  checkpoinLed  t^sk,  th»  Executive  queues 
the  AST  (FIFO),  brings  the  task  into  memory,  and  then 
activates  trie  AST  when  the  task  returns  to  memory. 

•  The  Executive  allocates  the  necessary  dynamic  memory  when  an 
AST  is  specified.  Thus,  no  AST  condition  licks  dynamic  mei.iory 
tor  data  storage  when  it  actually  cccurs.  The  AST  re-usLS  the 
storage  allocated  for  I/O  and  Mark  Time  directives. 
Therefore,  r.o  additional  dynamic  storage  is  required. 

•  Two  directives.  Disable  AST  Recognition  and  Enable  AST 
Recognition,  allow  a  program  to  queue  ASTs  for  subsequent 
ex'jcution  during  critical  sections  of  code.  (A  critical 
section  might  bf  one  that  accesses  data  bases  also  accessed  by 
AST  service  r^.utines,  for  example.)  If  ASTs  occur  while  AST 
recognition  is  disabled,  they  are  queued  (FIFO)  and  then 
processed  when  AST  recognition  is  enabled. 


2.3.4   AST  Service  Routines 

When  an  AST  occurs,  the  Executive  pushes  the  task's  Wait  For  mask 
word,  the  DSW,  the  PS,  and  the  PC  onto  the  task's  stack.  This 
information  saves  the  state  of  the  task  so  that  the  AST  service 
routine  has  access  to  all  the  available  Executive  services.  The 
preserved  Wait  For  mask  word  allows  the  AST  routines  to  establish  the 
conditions  necessary  to  unblock  the  waiting  task.  Depending  on  the 
reason  for  the  AST,  the  stack  ma/  also  contain  additional  parameters. 
Note  that  the  task's  general  purpose  registers  R0-R5  and  SP  are  not 
saved.  If  the  routine  makes  use  of  them,  it  must  save  and  restore 
their  itself. 

On  RSX-llM  systems  that  support  stop-bit  synchronization  or 
checkpointing  during  buffered  I/O  and  all  RSX-llM-PLU^  systems,  the 
Wait  For  mask  word  comes  from  the  offset  T. EFLM  in  the  task's  Task 
Control  Block  (TCB)  .  On  systems  that  do  not  support  those  features, 
the  Wait  For  mask  word  comes  from  the  offset  H.EFLM  i  r.  the  task's 
header.     Its   value  and  the  event  flag  range  co  which  it  corresponds 
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depend  on  the  last  Wait  For  or  Stop  For  directive  issued  by  the  task. 
For  example,  if  the  last  such  directive  issued  was  Walt  For  Sinqle 
Event  Flag  42,  the  mask  word  has  a  value  of  1000(8)  and  the  event  flag 
range  is  from  33  to  48.  Bit  0  of  the  mask  word  represents  flag  33, 
bit  1  represents  flag  34,  and  so  on. 

The  Wait  For  mask  word  is  meaningless  if  the  task  has  not  issued  any 
type  of  Walt  For  or  Stop  For  directive. 

Your  code  should  not  attempt  to  modify  the  Walt  For  rr.ask  while  in  the 
AST  routine.  For  example,  putting  a  zero  In  the  Wait  For  mask  results 
In  an  unclearable  Wait  For  state. 

After  processing  an  AST,  the  task  must  remove  the  trap-dependent 
parameters  from  its  stack;  that  is,  everything  from  the  top  of  the 
stack  down  to,  but  not  including,  the  task's  Directive  Status  Word. 
It  must  then  Issue  an  AST  Service  Exit  directive  with  the  stack  set  as 
Indicated  in  the  description  of  that  directive  (see  Section  5.3.4). 
When  the  AST  service  routine  exits,  it  returns  control  to  one  of  two 
places:   another  AST,  or  the  original  task. 

There  are  13  variations  on  the  format  of  the  task's  stack,  as  follows: 

•  If  a  task  needs  to  be  notified  when  a  Floating  Point  Processor 
exception  trap  occurs,  it  Issues  a  Specify  Floating  Point 
Processor  Exception  AST  directive.  If  the  task  specifies  this 
directive,  an  AST  will  occur  when  a  Floating  Point  Processor 
exception  trap  occurs.  The  stack  will  contain  the  following 
values • 

SP+12  —  Event  flag  mask  word 

SP+10  --  PS  of  task  prior  to  AST 

SP+06  --  PC  of  task  prior  to  AST 

SP+O-i  —  Task's  Directive  Status  Word 

SP+02  --  Floating  exception  cod' 

SP+00  --  Floating  exception  address 

NOTE 

Refer  to  the  appropriate  processor 
handbook  for  a  description  of  the  FPU 
exception  code  values. 

•  If  the  task  needs  to  be  notified  of  power  failure  recoveries. 
It  Issues  a  Specify  Power  Recovery  AST  directive.  An  AST  will 
then  occur  when  the  power  Is  restored  if  the  task  is  not 
checkpo inted  .   The  stack  will  contain  the  following  values: 

SP+0*S  --  Event  flag  mask  word 

SP+04  —  PS  of  task  prior  to  AST 

SP+02  —  PC  of  task  prior  to  AST 

SP+00  —  Task's  Directive  Status  Word 

•  If  a  task  needs  to  be  notified  when  it  receives  either  a 
message  or  a  reference  to  a  common  area,  it  issues  either  a 
Specify  Receive  Data  AST  or  a  Specify  Receive  By  Reference  AST 
directive.  An  AST  will  cccur  when  the  message  or  common 
reference  Is  sent  to  the  task.  The  stack  will  contain  the 
following  values: 
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SP+06  —  Event  flag  mask  word 

SP+04  --  PS  of  task  prior  to  AST 

SP+02  --  PC  of  task  prior  to  AST 

SP+00  --  Task's  Directive  Status  Word 


When  a  task  queues  an  I/O  request  and 
AST  service  entry  point, 
the  I/O  request.   The 
values : 


specifies  aa  appropriate 

....,  _..  ..„ occur  upon  completion  of 

task's  stack  will  contain  the   following 


an  AST  will 


SP+10   —   Event  flag  mask  word 
SP+06   --   PS  of  task  prior  to  AST 
SP+04   —   PC  of  task  prior  to  AST 
SP+02   —   Task's  Directive  Status  Word 
SP+00   —  Address  of  I/O  status  block  for  I/O  request 
zero  if  none  was  specified) 


(or 


•  When  a  task  issues  a  Mark  Time  directive  and  specifies  an 
appropriate  AST  service  entry  point,  an  AST  will  occur  when 
the  indicated  time  interval  has  elapsed.  The  task's  stack 
will  contain  the  following  values: 


SP+10   --   Event  flag  mask  word 
SP+06   --   PS  of  task  prior  to  AST 
SP-f04   --   PC  of  task  prior  to  AST 
SP+02   —   Task's  Directive  Status  Word 
SP+00   --   Event   flag   number   (or   zero 
speci  f ied) 


if 


was 


An  offspring  task,  connected  by  a  Spawn,  Connect,  or  Send, 
Request  And  Connect  directive,  returns  .status  to  the  connected 
(parent)  task(s)  upon  exiting  by  the  Exit  AST.  The  parent 
task's  stack  contains  the  following  values: 

SP+10  --  Event  flag  mask  word 

SP+06  --  PS  of  task  prior  to  AST 

SP+04  --  PC  of  task  prior  to  AST 

SP+02  —  Task's  Directive  Status  Word 

SP+00  —  Address  of  exit  status  block 


If  a  command  arrives   for   a   CLI,   the 
routine  is  entered.   The  stack  contains: 


Command   Arrival   AST 


SP+10  —  Event  flag  mask  word 

SP+06  --  PS  of  task  prior  to  AST 

SP+04  --  PC  of  task  prior  to  AST 

SP+02  —  Task's  Directive  Status  Word 

SP+00  --  Command  buffer  address 

•  If  a  parent  task  issues  a  Create  Virtual  Terminal  directive, 
the  input  and  output  AST  routines  are  entered.  The  task's 
stack  contains  the  following  values: 

SP+14  --  Event  flag  mask  word 

SP+12  —  PS  of  task  prior  to  AST 

SP+10  —  PC  of  task  prior  to  AST 

SP+06  —  Task's  Directive  Status  Word 


SP+04  —  Third  parameter  word  (Vertical  Format 
Control  -  VFC)  of  the  offspring  request 

SP+02   —   Byte  count  of  offspring  request 

SP+00  —  Virtual  terminal  unit  number  (low  byte);  I/O 
subfunction  code  of  offspring  request  (high 
byte) 
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•  If  the  Attach/Detach  AST  routine  Is  entered  for  a  virtual 
terminal  attach,  the  task's  stack  contains  the  following 
values : 


SP+14   —   Event  flag  mask  word 

SP+12   —   PS  of  task  prior  to  AST 

SP+10      —      PC   of    task    prior    to    AST 

SP+06   —   Task's  Directive  Status  Word 

SP+04   --   Second  word  of  offspring  task  name 

SP+02   —   First  word  of  offspring  task  name 

SP+00   —   Virtual  terminal  unit  number   (low  byte) ; 

suDfunction   code   of   offspring   request 

byte) 


I/O 
(high 


•  If  the  Attach/Detach  AST  routine  Is  entered  for  a  virtual 
terminal  detach,  the  task's  stack  contains  the  following 
values : 

SP+14   —   Event  flag  mask  word 

SP+12   --   PS  of  task  prior  to  AST 

C'P+IO      —      PC  of  task  prior  to  AST 

SP+06      —     Task's   Directive   Status   Word 

SP+04   —   Second  word  of  offspring  task  name  =  0 

SP+02   —   First  word  of  offspring  task  name  =  0 

SP+00   —   Virtual  terminal  unit  number   (low  byte);    I/O 

subfunction   code   of   offspring   request   (high 

byte) 


•   If  a  task  issues  a  Specify  Parity   Error   AST 
parity  error  AST  service  routine  is  entered, 
contains  the  following  values: 


directive,   the 
The  task's  stack 


SP+62  - 
SP+60  - 
SP+56  - 
SP+54  - 
SP+52  - 
SP+50  - 
SP+46  - 
SP+4  4  - 
SP+«2  - 
SP+40  - 
SP+36  - 
SP+34  - 
SP+32  ■ 
SP+30  - 
SP+26  - 
SP+24  - 
?rr22  - 
Sk+20  - 
SP+I6  - 
SP+14  - 
SP+12  - 
SP+10  - 
SP+06  - 
SP+04  - 
SP+02  - 
system* 
SP+00  - 
(52) 


-•  Event    flag    mask    word 

-  PS    of    task    prior    to    AST 

-  PC   of    task    prior    to    AST 

-  Task's   Directive   Status   Word 


Contenv.s  of  memory  parity  CSRs 
(hardware-dependent  Information) 


0) 


Contents  of  cache  control  register 
Contents  of  memory  system  error  register 
Contents  of  high  error  address  register 
Contents  of  low  error  address  register 
Processor  identification  (single  processor 
I 
Number  of  bytes  to  add  to  SP  to  clean  tiie  stack 


•   If  a  task  becomes  aborted  via  directive,  DCL  or  MCR  when   the 

Specify  Requested  Exit  AST  (SREAS)  is  in  effect,  the  abort  AST 

is  entered  with  the   task's   stack   containing   the  following 
values : 
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SP+06  —  Event  flag  mask  word 

SP+04  —  PS  of  task  prior  to  AST 

SP-t-02  --  PC  of  task  prior  to  AST 

SP+00  —  Task's  Directive  Status  Word 

•  If  a  task  becomes  aborted  by  directive,  DCL,  or  MCR  when  the 
Extended  Specify  Requested  Exit  AST  (SREXS)  is  in  effect,  the 
abort  AST  is  entered.  The  task's  stack  contains  the  following 
values : 

SP+12  --  Event  flag  mask  word 

SP+10  --  PS  of  task  prior  to  AST 

SP+06  --  PC   of    t^sk   prior    to    AST 

SP+04  —  DSW  of  task  prior  to  AST 

SP-t-02  —  Trap  dependent  parameter 

SP•^00  —  Number  of  bytes  to  add  to  SP  to  clean  the  stack 

•  If  a  task  issues  a  QIO  10. ATA  function  to  the  full-duplex 
terminal  driver,  unsolicited  terminal  inpu"-  will  cause  entry 
into  the  AST  service  routine.  Upon  entry  into  the  routine, 
the  task's  stack  containing  the  following  values:  ^ 


SP-^10   —   Event  flag  mask  word 
SP-f06   --   PS  of  task  prior  to  AST 
SP-t-04   —   PC  of  task  prior  to  AST 
SP-t-02   --   Task's  Directive  Status  Word 
SP-t-00   —   Unsolicited  character  in  low  byte; 
In  the  high  byte 


parameter 


2.4   STOP-BIT  SYNCHRONIZATION 

Stop-bit  synciironl  zat  ion  allows  tasks  to  be  checkpolnted  during 
terminal  (buffered)  I/O  or  while  waiting  for  an  event  to  occur  (for 
example,  an  event  flag  to  become  set  or  an  Unstop  directive  to  become 
issued).  You  can  control  synchronization  between  tasks  by  the  setting 
of  the  task's  Task  Control  Block  (TCB)  stop  bit. 

When  the  task's  stop  bit  is  st.t,  the  task  is  blocked  from  further 
execution,  Its  priority  for  memory  alloca^lon  effectively  drops  to 
zero,  and  it  may  be  checkpolnted  by  any  other  task  in  the  system, 
regardless  of  priority.  If  checkpolnted,  the  task  remains  out  of 
memory  until  its  stop  bit  is  cleared,  at  which  time  the  task  becomes 
unstopped,  its  normal  priority  for  memory  allocation  becomes  restored, 
and  it  is  considered  for  memory  allocation  based  on  the  restored 
pr  ior 1 ty. 

If  the  stopped  task  receives  an  AST,  it  becomes  unstopped  until  it 
exits  the  AST  routine.  Memory  allocation  for  the  task  during  the  AST 
routine  is  based  on  the  task's  priority  prior  to  the  sf.opped  state. 
Note  that  a  task  cannot  be  stopped  when  an  AST  is  in  progress,  but  the 
AST  routine  can  Issue  either  an  Unstop  or  Set  Event  Flag  directive  to 
reference  the  task.  This  causes  it  to  remain  unstopped  after  it 
issuc-s  the  AST  Servlci*  Exit  directive. 

There  ars  three  ways  In  which  a  nonpr Iv 1 leged  task  can  become  stopped 
and  three  corresponding  ways  to  become  unstopped.  Only  one  method  for 
stopping  a  task  can  be  applied  at  a  time. 
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•  A  task  Is  stopped  whenever  It  is  In  a  Wait  For  state  and  has 
outstanding  buffered  I/O.  A  task  is  unstopped  when  the 
buffered  I/O  is  completed  or  when  the  Walt  For  condition  is 
sat  1  sf i  ed  . 

•  You  can  stop  a  task  for  event  flag{s)  by  issuing  the  Stop  For 
Single  Event  Flag  directive  or  the  Stop  For  Logical  OR  Of 
Event  Flags  directive.  In  this  case,  the  task  can  only  be 
unstopped  by  setting  the  specified  event  flag's). 

•  You  can  stop  a  task  by  issuing  a  Stop;  the  Receive  Data  Or 
Stop  directive,  or  the  Get  Command  Command  for  Command 
Interpreter  directive.  In  this  case,  th«  task  can  only  be 
unstopped  by  Issuing  the  Unstop  directive  or  by  the  MCR  or  DCL 
Unstop  command . 

You  cannot  stop  a  taslf  when  an  AST  Is  In  progress  (AST  state).  Any 
directives  that  can  cause  a  task  to  become  stopped  are  illegal  at  the 
AST  state. 

When  a  task  Is  stopped  for  any  reason  at  the  task  state,  it  jan  still 
receive  ASTs .  If  the  task  has  been  checkpo inted ,  it  becomes  eligible 
for  entrance  bark  into  memory  when  an  AST  is  queued  for  it.  The  task 
retains  its  normal  priority  in  memory  while  it  is  at  the  AST  state  or 
has  ASTs  queued.  Once  it  has  exited  the  AST  routine  w*  th  -  ^  •^her 
ASTs  qi-eued,  the  task  is  again  stopped  and  effectlvel,.  .■<»ro 
priority  for  memory  allocation. 

You  can  use  six  directives  tor  stop-bit  synchronization: 

•  Stop  -  This  directive  stops  the  issuing  task  and  cannot  be 
issued  at  the  AST  state. 

•  Receive  Data  Or  Stop  and  Varlablt  Receive  Data  Or  Stop  -  These 
directives  attempt  to  dequeue  send  dat.i  packers  from  the 
specified  task  (or  any  task  If  none  is  specified) .  If  there 
is  no  such  packet  j  be  dequeued,  the  issuing  tisk  is  stopped. 
These  directives  cannot  be  Issued  at    the  AST  state. 

•  Stop  For  Logical  OR  Of  Event  Flags  -  This  directive  s-.:)ps  the 
issuing  task  until  the  specified  fl-igs  in  the  specified  group 
of  local  event  flags  become  set.  If  any  of  the  specified 
event  flags  are  already  set,  the  task  does  not  become  stopped. 
This  directive  cannot  be  issued  at  the  AST  state. 

•  Stop  For  Single  Event  Flag  -  This  directive  stops  the  issuing 
task  until  the  indicated  local  event  flag  becomes  set.  If  the 
specified  event  flag  (s  already  set,  the  task  does  not  become 
stopoed.   This  directive  cannot  be  Issued  at  :i.e    AST  state. 

•  Unstop  -  This  directive  unstops  a  task  that  has  become  stopped 
by  the  Stop  or  Receive  Data  Or  Stop  directive. 

•  Get  Command  for  Command  Interpreter  -  This  directive  stops  a 
CLI  task  when  there  is  no  command  queued  for  it.  The  GC.CST 
option  must  be  specified  to  force  the  task  to  stop.  See 
Section  5.3.30.  This  directive  .-annot  be  issued  at  the  AST 
state . 
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CHAPTER  3 
MEMORY  MANAGEMENT  DIRECTIVES 


Within  the  framework  of  memory  management  directives,  this  chapter 
discusses  the  concepts  of  extended  logical  address  space,  regions,  and 
virtual  address  windows. 


3.1   ADDRESSING  CAPABILITIES  OF  AN  RSX-llM  TASK 

Without  overlaying  of  tasks,  an  RSX-llM  task  cannot  explicitly  refer 
to  a  location  with  an  address  greater  than  177777  (32K  words).  The 
16-bit  word  size  of  the  PDP-11  imposes  this  restriction  on  a  task's 
addressing  capability.  Overlaying  a  task  means  that  it  must  first  be 
divided  into  segments:  a  single  root  segment,  which  is  always  in 
memory;  and  any  number  of  overlay  segments,  which  can  be  loaded  into 
memory  as  required.  Unless  an  RSX-llM  task  uses  the  memory  management 
directives  described  in  this  chapter,  the  combined  size  of  the  task 
segments  concurrently  in  memory  cannot  exceed  32K  words. 

When  resident  task  segments  cannot  exceed  a  total  of  32K  words,  a  task 
requiring  large  amounts  of  data  must  access  data  that  reside  on  lisk. 
Data  are  disk  based  not  only  because  of  limited  memory  space  but  also 
because  transmission  of  large  amounts  of  data  between  tasks  is  only 
practical  by  means  of  disk.  An  overlaid  task,  or  a  task  that  needs  to 
access  or  transfer  large  amounts  of  data,  incurs  a  considerable  amount 
of  transfer  activity  over  and  above  that  caused  by  the  task's 
function. 

Task  execution  could  obviously  be  faster  if  all  or  a  greater  portion 
of  the  task  were  resident  in  memory  at  run  time.  RSX-llM  includes  a 
group  of  memory  management  directives  that  provide  the  task  with  this 
capability.  The  directives  overcome  the  32K-word  addressing 
restriction  by  allowing  the  task  to  dynamically  change  the  physical 
locations  that  are  referred  to  by  a  given  range  of  addresses.  With 
these  directives,  a  task  can  increase  its  execution  speed  by  reducing 
its  disk  I/O  requirements  at  the  expense  of  increased  physical  memory 
requirements. 

On  RSX-llM-PLUS  systems  you  can  effectively  triple  the  memory 
available  foi  tasks  on  PDP-11  systems  that  aro  capable  of  operating  in 
supervisor  Fode  through  the  use  of  supervisor-mode  library  routines 
and  separate  user-mode  I-  and  D-space.  Supervisor-mode  library 
routines  are  instruction-only  routines  that  are  mapped  into 
supervisor-mode  I-space  (up  to  32K  words  maximum) .  User  task 
parameters,  stack,  and  any  locations  that  may  be  written  are  mapped 
?nto  supervisor-mode  D-space  (up  to  32K  words  maximum).  User  tasks 
that  use  I-  and  D-space  may  consist  of  up  to  32K  words  of  instructions 
and  32K  words  of  data. 
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3.1.1   Address  Mopping 

In  a  mapped  system,  the  Liser  does  not  r.eed  to  knov  where  a  task 
resides  in  physical  memory.  Mapping,  the  process  of  associating  task 
addresses  with  available  physical  memory,  is  transparent  to  tne  user 
and  is  accomplished  by  the  KT] 1  memory  management  hardware.  (See  the 
appropriate  PDP-11  processor  handbook  for  a  description  of  the  KTll.) 
When  a  task  references  a  location  (virtual  address),  the  KTll 
determines  the  physical  address  in  memory.  The  memory  management 
directives  use  the  KTll  to  perform  address  mapping  at  a  level  that  is 
visible  to  and  controlled  by  the  user. 


3.1.2  Virtual  and  Logical  Address  Space 

The  three  concepts  defined  below,  physical  address  space,  logical 
address  space,  and  virtual  address  space,  provide  a  basis  for 
understanding  the  functions  performed  by  the  memory  management 
directives  : 

•  Physical  Address  Space  --  A  task's  physical  addr'^ss  space  Is 
the  entire  set  of  physical  memory  addresses. 

•  Logical  Address  Space  --  A  task's  logical  address  space  is  the 
total  amount  of  physical  memory  to  which  the  tafjk  has  access 
rights.  This  includes  various  areas  called  regions  (see 
Section  3.3).  Each  region  occupies  a  contiguous  block  of 
memory. 

•  Virtual  Address  Space  --  A  task's  virtual  address  space 
corresponds  to  the  32K-word  addross  rsngs  imposed  by  the 
PDP-ll's  16-bit  word  length.  The  task  can  d'vlde  its  virtual 
address  space  into  segments  called  virtual  address  windows 
(see  Section  3.2). 

If  the  capabilities  supplied  by  the  RSX-llM  memory  management 
directives  were  not  available,  a  task's  virtual  address  space  and 
logical  address  space  would  directly  correspond;  a  single  virtual 
address  would  always  point  to  the  same  logical  location.  Both  types 
of  address  space  would  have  a  maximum  size  of  32K  words.  However,  the 
ability  of  the  memory  management  directives  to  assign  or  map  a  range 
of  virtual  addresses  (a  window)  to  different  logical  areas  (regions) 
enables  the  user  to  extend  a  task's  logical  address  space  beyond  32K 
words. 


3.1.3  S-jpervisor-Mode  Addressing 

RSX-llM-PLUS  supports   PDP-11   processors  capable  of  operating   in 
supervisor  mode.    The  supervisor  mode  is  one  of  three  possible  modes 


Supervisor-mode  support  doubles  the  instruction  space  available  to 
tasks  because  16  APHs  (8  User-mode  I-space  and  8  supervisor-mode 
I-space)  are  available  for  address  mapping.  The  contents  of  user-mode 
D-space  APRs  (I-space  APRs  on  systems  that  do  not  support  user  data 
space)  are  copied  into  supervisor-mode  D-space  APRs  to  allow 
supervisor-mode  routines  to  access  user-mode  data.  (Refer  to  the 
appropriate  PDP-11  processor  handbook  for  a  complete  description  of 
address  mapping,  memory  management,  and  the  various  APR  registers). 
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3.1.4  Mapping  Structure  of  I-  and  D-Space  Tasks 

RSX-llM-PLUS  supfKjrts  user-mode  I-  and  D-space.  Tasks  that  do  not  use 
D-space  execute  with  I-  and  D-space  ov^rmapped.  However,  these  tasks 
may  create  D-spaco  windows.  This  allows  tasks  to  increase  the  total 
virtual  size  without  a  full  implementation  of  I-  and  D-space. 

Tasks  in  which  the  Task  Builder  has  separated  the  T-space  and  D-space 
structures  are  mapped  separately  (I-  and  D-spaco  are  not  overmapped). 
The  overall  mappinq  structure  for  these  tasks  is  as  follows: 

Window  0        Root  I-space. 

Window  1        Task  Header,  stack  and  root  D-space. 

Window  2  I-space  of  the  read-only  section  if  a  multi-user 
task.  Memory  resident  overlays  if  not  a 
multi-user  task. 

Window  3  D-space  of  the  read-only  section  if  a  multi-user 
task.  Memory  resident  overlays  if  not  a 
multi-user  task. 

Window  4        Memory  resident  overlays. 


The  multi-user  section  of  a  multi-user  task  is  also  separated  into  I- 
and  D-space  areas.  Memory  resident  libraries  are  not  separated  and 
are  normally  mapped  by  both  I-  and  D-^space.  Common  regions  are  also 
normally  mapped  through  D-space  only.  However,  the  memory  management 
directives  can  be  used  to  attach  to  and  map  a  data  common  with  an 
explicit  D-space  window. 


3.2   VIRTUAL  ADDRESS  WINDOWS 

In  order  to  manipulate  the  mapping  of  virtual  addresses  to  various 
logical  areas,  you  must  first  divide  a  task's  32K  of  virtual  address 
space  into  segments.  These  segments  are  called  virtual  address 
windows.  Each  window  encompasses  a  contiguous  range  of  virtual 
addresses,  which  must  begin  on  a  4K-word  boundary  (that  Is,  the  first 
address  must  be  a  multiple  of  4K ) .  The  number  of  windows  defined  by  a 
task  can  vary  from  1  to  7  for  RSX-llM  tasks  and  from  1  to  23  for 
RSX-llM-PLUS  tasKS.  For  all  tasks,  window  0  is  not  available  to  the 
user.  For  tasks  using  I-  and  D-space,  windows  0  and  1  are  not 
available  to  the  user.  The  size  of  each  window  can  range  from  a 
minimum  of  32  words  to  a  naximun  of  32K  words. 

A  task  that  includes  directives  to  manipulate  address  windows 
dynamically  must  have  window  blocks  set  up  in  its  task  header.  The 
Executive  use?  window  blocks  to  identify  and  describe  each  currently 
existing  window.  You  specify  the  required  number  of  additional  window 
blocks  (the  number  used  for  windows  created  by  the  memory  management 
directives)  to  be  set  up  by  the  Task  Builder  when  linking  the  task 
(see  the  RSX-1 IM/M-PLUS  Task  Bui Ider  Reference  Manual) .  The  number  of 
blocks  that  you  specify  should  equal  the  maximum  number  of  windows 
that  will  exist  at  any  one  tine  when  the  task  is  running. 
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A  window's  irient  i  f  icat  Ion  is  a  number  from  0  to  !S.  t'or  either  unor 
or  supervisor  windows  on  systems  that  support  supervisor-mode 
libraries  (0  to  23  for  systems  with  user  and  supervisor  I-  and  D- 
space)  ,  which  is  an  Index  to  the  window's  cor  re:;pond  i  n;j  window  block. 
The  address  window  identified  by  0  is  the  window  that  maps  the  task's 
header  and  root  segment.  In  tasks  usinq  I-  and  0-space,  window  0  maps 
the  task's  root  instruction  segment.  Window  1  maps  the  task's  header, 
stack,  and  root  data  segment.  The  Task  Builder  automatically  creates 
window  0,  which  is  mapped  by  the  Executive  and  cannot  be  specified  in 
any  d  i  rect  i ve  . 

Figure  3-1  shows  the  virtual  address  space  of  a  task  divided  into  four 
address  windows  (windows  0,  1,  2,  and  3).  The  shaded  areas  Indicate 
portions  of  the  address  space  that  are  not  included  In  any  window  (9K 
to  12K  and  23K  to  24K).  Addresses  that  fall  within  the  ranges 
corresponding  to  the  snaded  areas  cannot  be  used. 

When  a  task  uses  memory  management  directives,  the  Executive  views  the 
relationship  between  the  task's  virtual  and  logical  address  space  in 
terms  of  windows  and  regions.  Unless  a  virtual  address  is  part  of  an 
existing  address  window,  reference  to  that  address  will  cause  an 
Illegal  iddress  trap  to  occur.  Similarly,  a  window  can  be  mapped  only 
to  an  area  that  Is  all  or  part  of  an  existing  region  within  the  task's 
logical  address  space  (see  Section  3.3). 

Once  a  task  has  defined  the  necessary  windows  and  regions,  it  can 
issue  memory  management  directives  to  perform  operations  such  us  the 
following : 

•   Map  a  window  to  all  or  part  of  a  region. 

e   Unmap  a  window  from  one  region  in  order  to  map  it   to   another 
reg  ion . 

e   Unmap  a  window  from  one  part  of  a  region  in  order  to  map  it  to 
another  part  of  the  same  region. 
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Figure  3-1   Virtual  Address  Windows 


3.3   REGIONS 

A  region  is  a  portion  of  a  physical  memory  to  which  a  task  has  (or 
potentially  may  have)  access.  The  current  window-to-region  mapping 
context  determines  that  part  of  a  task's  logical  address  spdce  that 
the  task  can  access  at  one  time.  A  task's  logical  address  s^-ace  can 
consist    of   various    types   of    regions: 

•  Task  region  --  A  contiguous  block  of  memory  In  which  the  task 
runs 

•  Static  common  region  --  An  area,  such  as  a  global  common  area, 
defined  by  an  operator  at  run  time  or  at  system  generation 
t  ime 


Nors 


On  RSX-llM  systems,  static  common 
regions  occupy  physical  memory  from  the 
time  they  are  created.  On  RSX-llM-PLUS 
systems,  they  are  dynamically  loaded 
whenever    needed. 
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•  Dynamic  region  --  A  region  created  dynamically  at  run  time   by 
issuing  the  memory  management  directives 

•  Shareable  region  --  A  read-only   portion  of   multiuser   tasks 
that  are  In  shareable  regions  (RSX-llM-PLUS  only) 

Tasks  refer  to  a  regior.  by  means  of  a  region  ID  returned  to  the  task 
by  the  Executive.  A  region  ID  from  0  to  23  refers  to  a  task's  static 
attachment.  Region  ID  0  always  refers  to  a  task's  task  re^^ion. 
Region  ID  1  always  rtfars  to  tha  raa*-only  (pura  coda)  portion  of 

multiuser  tasks.  All  other  region  IDs  are  actually  addresses  of  the 
attachment  descriptor  maintained  by  the  Executive  in  the  system 
dynamic  storage  area. 

Figure  3-2  shows  a  sample  collection  of  regions  that  could  make  up  a 
task's  logical  address  space  at  some  given  time.  The  header  and  root 
segment  are  always  part  of  the  task  region.  Since  a  region  occupies  a 
contiguous  area  of  memory,  each  region  Is  shown  as  a  separate  block. 

Figure  3-3  illustrates  a  possible  mapping  relationship  between  the 
windows  and  regions  shown  in  Figures  3-1  and  3-2. 


Shared  Regions 


3.3.2   Attaching  to  Regions 

Attaching  Is  the  process  by  whic^  a  region  becomes  part   of  a      task's 

logical   address   jpace.   A  task  can  map  only  a  region  that  is  part  of 

the  task's  logical  address  space.   There  are  three  ways   to  attach  a 
task  to  a  region: 

•  All  tasks  arf  automatically  attached  to  regions  that  are 
linked  to  then  at  task-build  time. 

•  A  task  can  issue  a  directive  to  attach  itsel.  to  a  named 
static  common  region  or  a  named  dynamic  region. 

•  A  task  can  request  the  Executive  to  attach  another  specified 
task  to  any  region  within  the  logical  addres;,  space  of  the 
request  ing  task . 

Attaching  identifies  a  task  as  a  jser  of  a   region  and  prevents   the 

system   from  deleting  a  region  until  all  user  tasks  have  been  detached 

from  it.   (It  should  be  noted  that  fixed  tasks   do  not  automatically 
become  detached  from  regions  ipon  exiting.^ 
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Figure  3-3   Mapping  Windows  to  Regions 
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In  RSX-llM-PLL'S  systems,  it  Is  possible 
to  avoid  multiple  attachment  descriptors 
when  sending  and  receiving  data  by 
reference.  Setting  the  WS.NAT  bit  in 
the  Window  Descriptor  Block  (see  Section 
3.5.2)  causes  tho  Executive  to  create  a 
new  attachment  descriptor  for  that 
region  only  if  necessary  (that  is,  if 
the  task  is  currently  not  attached  to 
the  regif  <i)  . 


3.  ,3   Region  Protection 

A  task  cannot  indiscriminately  attach  to  any  reg'.on.  Each  region  1  s 
a  protection  mask  to  prevent  unauthorized  access.  The  mask  indicat  s 
the  types  cf  access  (read,  write,  extend,  delete)  allowed  for  ec  h 
category  of  user  (system,  owner,  group,  world).  The  Executive  chei  s 
that  the  requesting  task's  User  Identification  Code  (UIC)  allows  it  -o 
make  the  attempted  access.  The  attempt  fails  if  the  protection  m  sk 
denies  that  task  the  access  it  wants. 

To  determine  when  tasks  may  add  to  their  logical  address  space  by 
attaching  regions,  the  following  points  must  be  considered.  (Note 
that  all  considerations  presume  there  is  no  protection  violation.): 

•  Any  task  can  attach  to  a  named  dynamic  region,  provided  it 
knows  the  name.  In  the  case  of  an  unnamed  dynamic  region,  a 
task  can  attach  to  the  region  only  a^ter  receiving  a  Send  By 
Reference  directive  from  the  task  that  created  the  region. 

•  Any  RSX-llM-PLUS  task  can  issue  a  Send  By  Reference  directive 
to  attach  another  task  to  any  region.  On  RSX-llM,  the  task 
region  itself  may  not  be  one  of  the  regions  involved.  The 
reference  sent  includes  the  access  rights  with  which  the 
receiving  task  attaches  to  the  region.  The  sending  task  can 
only  grant  accept  ri'-jhts  that  it  has  itself. 

•  Any  task  can  map  to  a  named  static  common  region. 


3.4   DIRECTIVE  SUMMARY 

This  section  briefly  describes  the  function  of  each  memory  management 
direct  i ve . 
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3.4.1   Create  Region  Directive  (CRRGS) 

Thu  Create  Region  directive  creates  a  dynamic  reqion  In  a  designated 
system-controlled  partition  and  optionally  attaches  the  issuing  task 
to  it  (see  Section  5.3.13). 


3.4.2   Attach  Region  Directive  (ATRG$) 

The  Attach  Region  directive  attaches  the   issuing   task   to   a   static 
common  region  or  to  a  named  dynamic  region  (see  Section  5.3.5). 


3.4.3   Detach  Region  Directive  (DTRG$) 

The  Detach  Region  directive  detaches  the  issuing  task  from  a  specified 
region.  Any  of  the  task's  address  windows  that  are  mapped  to  the 
region  are  automatically  unmapped  (see  Section  5.3.19). 


3.4.4   Create  Address  Window  Directive  (CRAWS) 

The  Create  Address  Window  directive  creates  an  address  window, 
establishes  its  virtual  address  basa  and  size,  and  optionally  maps  the 
window.  Any  other  windows  that  overlap  with  the  range  of  addresses  of 
the  new  window  are  first  unmapped  and  then  eliminated  (see  Section 
5.3.11)  . 


3.4.5   Eliminate  Address  Window  Directive  (ELAWS) 

The  Eliminate  Address  Window  directive  eliminates  an  existing   address 
window,  unmapping  it  first  if  necessary  (see  Section  5.3.20). 


3.4.6   Map  Address  Window  Directive  (MAPS) 

The  Map  Address  Window  directive  maps  an  existing  window  to  an 
attached  region.  The  mapping  begins  at  a  specified  offset  from  the 
start  of  the  region  and  goes  to  a  specified  length.  If  the  window  is 
already  mapped  elsewhere,  the  Executive  unmaps  it  before  carrying  out 
the  map  assignment  described  in  the  directive  (see  Section  5.3.40). 


3.4.7   Unmap  Address  Window  Directive  (UMAPS) 

The  Unmap  Address  Window  directive  unmaps  a  specified  window.  After 
the  window  has  been  unmapped,  its  virtual  address  range  cannot  bo 
referenced  until  the  task  issues  another  mapping  directive  (see 
Section  5. 3. 85)  . 


3.4.8   Send  By  Reference  Directive  (SREF$) 

The  Send  By  Reference  directive  inserts  a  packet  containing  a 
reference  to  a  region  into  the  receive  queue  of  a  specified  task.  The 
receiver  task  is  automatically  attached  to  the  region  referred  to  (see 
Section  5. 3. 74)  . 
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3.4.9   Receive  By  Reference  Directive  (RREP$) 

The  Receive  By  Referenc!  directive  requests  tho  Executive  first  to 
select  the  next  packet  from  the  recelve-by-ref erence  queue  of  the 
Issuing  task,  and  then  to  make  the  Information  in  the  packet  available 
to  the  task.  Optionally  the  directive  can  map  a  window  to  the 
referenced  region  or  cause  the  t^sk  to  exit  if  the  queue  does  not 
contain  a  recelve-by-ref erence  packet  (see  Section  5.3.55). 


3.4.10   Get  Mapping  Context  Directive  (GMCX$) 

The  Get  Mapping  Context  directive  causes  the  Executive  to  return  to 
the  issuing  task  a  description  of  the  current  wlndow-to-reg ion  mapping 
assignments.  The  description  is  in  a  form  that  enables  the  user  to 
restore  the  mapping  context  through  a  series  of  Create  Address  Window 
directives  (see  Section  5.3.34). 


3.4.11   Get  Region  Parameters  Directive  (GREG$) 

The  Get  Region  Parameters  directive  causes  the  Executive  to  supply  the 
Issuing  task  with  information  about  either  its  task  region  (if  no 
region  ID  Is  given)  or  an  explicitly  specified  region  fsee  Section 
5.  3. 36)  . 


3.5   USER  DATA  STRUCTURES 

Most  memory  management  directives  are  individually  capable  of 
performing  a  number  of  separate  actions.  For  example,  a  single  Create 
Address  Window  directive  can  anmap  and  eliminate  up  to  seven 
conflicting  address  windows,  create  a  new  window,  and  map  the  new 
window  to  a  specified  region.  The  complexity  of  the  directives 
requires  a  special  means  of  communication  between  the  user  task  and 
the  Executive.  The  communication  is  achieved  through  data  structures 
thut : 

•  Allow  the  task  to  specify  which  directive  options  It  wants  the 
Executive  to  perform 

•  Permit  the  Executive  to  prcvide  the  task   with   details   about 
the  outcome  of  the  requested  actions 

There  are  two  types  of  user  data  structures  that  correspond  to  the  two 
key  elements  (regions  and  address  windows)  manipulated  by  the 
directives.   The  structures  are  called: 

•  The  Region  Definition  Block  (RDB) 

•  The  Window  Definition  Block  (WDB) 


Every  memory  manag 
one  of  these  st 
and  tile  Executive. 
Parameter  Block 
Symbolic  address  o 
locations  within  a 
these  locations  to 
the  Executive  ha 
values  to  various 
taken  and  to  pro 
operations . 


ement  directive,  except  Get  Region  Parameters,  uses 
ructures  as  its  communications  area  between  the  task 
Each  directive  issued  includes  in  the  Directive 
(DPB)  a  pointer  to  the  appropriate  definition  block, 
ffset  values  are  assigned  by  the  task,  pointing  to 
n  RDB  or  a  WDB.  The  task  can  change  the  contents  of 
define  or  modify  the  directive  operation.  After 
s  carried  out  the  specified  operation,  it  assigns 
locations  within  the  block  to  describe  the  actions 
vide  the  task  with  information  useful  for  subsequent 
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3.5.1   Region  Definition  Block  (RDB) 

Figure  3-4  illustrates  the  format  of  an  RDB.  In  addition  to  the 
symbolic  offsets  defined  In  the  diagram,  the  region  status  word  R.GSTS 
contains  defined  bits  that  may  be  set  or  cleared  by  the  Executive  or 
the  task.  (RSX-llM  reserves  undefined  bits  for  future  expansion.)  The 
bits  and  their  definitions  follow. 

Bit  Definition 

RS.CRR«^100000       Region  was  successfully  created. 

RS.UNM=40000        At  least  one  window  was  unmapped  on  a  ietach. 

RS.MDL  =  200  Mark  region   for   deletion   on   l.^st   detach. 

When  a  region  is  created  by  means  of  a  CRRG$ 
directive  it  is  normally  marked  for  deletion 
on  laot  detach.  However,  if  RS.NDL  is  set 
when  the  CRRGS  directive  is  executed,  the 
region  is  not  marked  for  deletion. 
Subsequent  execution  of  a  DTRGS  directive 
with  RS.MDL  set  marks  the  region  for 
deletion . 

RS.NDL^IOO  Created   region   is   not   to   be   marked   for 

deletion  on  last  detach. 

RS.ATT=40  Attach  to  created  region. 

RS.NEX'=20  Created  region  is  not  ext^^ndable. 

RS.DEL=10  Delete  access  desired  on  attach. 

RS.EXT=4  Extend  access  desired  on  attach. 

RS.WRT=2  Write  access  desired  on  attach. 

Rr>.RED=l  Read  access  desired  on  attach. 

These  symbols  are  defined  by  the  RDBDF$  macro,  as  described  in  section 
3.5. 1.  1. 

The  three  memory  management  directives  that  require  a  pointer  to  an 
RDB  are: 

Create  Region  (CRRG$) 
Attach  Region  (ATRGS) 
Detach  Region  (DTRGS) 

When  a  task  issues  one  of  these  directives,  the  Executive  clears  the 
four  high-order  bits  in  the  region  status  word  of  the  appropriate  RDB. 
After  completing  the  directive  operation,  the  Executive  sets  the 
RS.CRR  or  RS.UNM  bit  to  indicate  to  the  task  what  actions  were  taken. 
The  Executive  never  modifies  the  other  bits. 
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Figure  3-4   Re^gion  Definition  Block 


3.5.1.1  Using  Macros  to  Generate  an  RDB  -  RSX-llM  provides;  two 
ma:ros,  RDBDF$  and  RDBBKS,  to  generate  and  define  an  RDB.  PDBDFS 
defines  the  offsets  and  status  word  bits  for  a  region  definition 
block;  RDBBK$  then  creates  the  actual  region  definition  block.  The 
format  of  RDBDFS  is: 

RDBDFS 

Since  RDBBKS  automatically  invokes  RDBDFS,  you  need  only  specify 
RDBBKS  in  a  module  that  creates  an  RDB.  The  format  of  the  call  to 
RDBBKS  is: 

RDBBKS    siz,nam,par,sts,pro 


SI  z 


nan 


par 


The    region    size    in    32-word    blocks, 


The    region    name    'RAD50) 


The    name    of    the    partition    in    which    to    create    the    region     (RAD50,. 
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Bit    definitions   of    the    region    status    word 


The    region's   default    protection   word 


The    sts    argument    sets    specified    bits    In    the    status    worJ      R.GSTS.         The 
argument    normally   has    the    following    format: 


bit 


<bltl (1 . . . ibitn] > 


A  defined  bit  to  be  set. 


The  argument  pro  is  an  octal  number.    The   16-blt   binary   equivalent 
specifies  the  region's  default  protection  as  follows: 


aits  15 


WORLD 


12  1, 


GROUP 


Each  of  the  four   catc) 
represonting  a  type  of  access: 


8  7        4  ]        0 
OWNf:      f.YSTEM 
CIS   four   bits,   with   each   bit 


Bit 


DELETE  [  EXTEND  I  WRITE   READ 


A  bit  value  of  0  Indicates  that  •  '.  type  of  access  is  to   be 

allowed;   a  bit  value  of  1  indicates  that  the  specified  type  of  access 
is  to  be  denied. 

The  macro  call 


RDBBKS 

102,  ,ALPHA.GEN,<RS.NDL!Rr>.A 

expands    to: 

.WORD 

0 

.WORD 

102. 

.RAD50 

/ALPHA/ 

.RAD50 

/GtN/ 

.WORD 

0 

•  WORD 

RS.NDLIRS.ATT! RS.WRT! RS.RED 

.WORD 

167000 

If  a  Create  Region  directive  pointed  ta  tho  RDB  .lefineM  by  this 
expanded  macro  call,  the  Executive  would  create  a  region  102  (decimal) 
32-word  blocks  in  length,  named  ALPHA,  In  a  partition  named  GEN.  The 
defined  bits  specified  in  the  sts  ariument  tell  the  Executive; 

•  Not  to  mark  the  region  for  deletion  on  the  \^st    detach 

•  To  attach  region  ALPHA  to  the  task  issui  ,g  the  directive  macro 

call 

•  To  c/rant  read  and  write  access  to  thp  attached  tfi;;k 

The  protection  word  specified  as  167000  (jctal)  assigns  a  di?f,iult 
protection  mask  to  the  region.  The  octal  numL/er,  which  has  a  binary 
equivalent  of  1110  1110  0000  0000,  grants  access  as  follows: 

System  (1110)  --  All  ac.-ess 

Owner  (1110)  --  All  access 

Group  (0000)  --  Read  access  only 

World  (0000)  --  Read  access  only 
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If  the  C'eate  Region  directive  Is  successful,  the  Executive  will  first 
return  to  the  issuing  task  a  region  ID  value  in  the  location  accessed 
by  symbolic  offset  R.GID,  and  then  will  set  the  defined  bit  RS.CRH  in 
the  status  word  R.GSTS. 


3.5.1.2  Using  FORTRAN  to  Generate  an  RDB  -  When  programming  in 
FORTRAN,  you  must  create  an  3-word,  single-precision  integer  array  as 
the  RDB  to  be  supplied  in  the  subroutine  calls; 

CALL  ATRG  (Attach  Region  directive) 
CALL  CRRG  (Create  Region  directive) 
CALL  DTRG      (Detach  Region  directive) 

(See  the  PDP-1 1  FORTRAN  Language  Reference  Manual  for  information  on 
the  creation  of  arrays.)  An  RDB  array  has  tHi  FoTlowlng  format: 

WorJ  Contents 

irdb(l)        Region  ID 

irdb(2)        Size  of  the  region  in  32-word  blocks 

irdb(3)        Region  name  (2  words  in  Radix-50  format) 
irdb(4) 

irdb(5)        Name  of  the  partition  that  contains  the  region 
irdb(6)         (2  words  in  Radix-50  format) 

irdb(7)        Region  status  word  (see   the   paragraph   following 
this  list) 

irdb(8)        Region  protection  code 

You  can  modify  the  region  status  word  irdb(7)  by  setting  or  clearing 
the  appropriate  bits.  See  the  list  in  Section  3.5.1  that  describes 
the  defined  bits.  The  bit  values  are  listed  alongside  the  symbolic 
offsets . 

Note  that  Hollerith  text  strings  can  be  converted  to  Radix-50  values 
by  calls  to  th?>  FORTRAN  library  routine  IRAD50  (see  the  appropriate 
FORTRAN  User' s  Guide) . 


3.5.2  Window  Definition  Block  (WDB) 

Figure  3-5  illustrates  the  format  of  a  WDB.  The  block  consists  of  a 
number  of  symbolic  address  offsets  to  specific  WDB  locations.  One  of 
the  locations  is  the  window  status  word  W.NSTS,  which  contains  defined 
bits  that  can  be  set  or  cleared  by  the  Executive  or  the  task. 
(RSX-llM  reserves  ail  undefined  bits  for  future  expansion.)  The  bits 
and  their  definitions  follow. 

Bit  Definition 

WS.CRW=100000       Addresr  window  was  successfully  created. 

WS.UNM=40000        At  least  one  window  was  unmapped  by  a   Create 

Address   Window,  Map  Address  Window,  or  Unmap 
Address  Window  directive. 

WS.ELW=200'D        At  least   one   window  was   eliminated   In   a 

Create   Address   Window  or  Eliminate  Address 
Window  d  i  rective . 
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W£.RRF»10000  Reference  was  successfully  received. 

WS.NBP-4000  Do  not  bypass  cache  for  CRAW$  directives. 

WS.BPS«4000  Always  bypass  cache  for  MAP$  directives. 

WS.RES«2000  Map  only  if  resident. 

WS.NAT^IOOO         Create   attacnment   de3criptor   only    if 

necessary  (for  Send  By  Reference  directives). 

WS.64B-400  Defines   thie    task'j    permitted    alignment 

boundaries    --   0   for   256-word   ;512-byte) 
alignment,  1  for  32-word  (64-byte)  alignment. 

WS.MAP=200  Window  is  to  be  mapped  in   a   Create   Address 

Window  or  Receive  By  Reference  directive. 

WS.RCX^IOO  Exit  If  no  references  to  receive. 

WS.SIS-40  Create  window  in  supervisor  I-space. 

WS.UDS-20  Create  this  window  in  user-mode  D-space. 

WS.DEL=10  Send  with  delete  access. 

WS.EXT=4  Send  with  extend  3ccess. 

WS.WRT=2  Send  wltn  write  access. 

or 
Map  with  write  access. 

WS.RED=1  Send  with  read  access. 
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Array 
Elsmeni 


iwdb  (U 


itMdb  (2) 


iwdb  (31 


Iwdb  (4) 


iwdb  (5) 


iwdb  (6) 


iwdb  (71 


Iwdb  IB) 


Symbolic 
Ottiet 


WNID 
W.NAPR 


WNBAS 


W.NSiZ 


WNRID 


W.NO?F 


WNLEN 


WNSTS 


W.NSRB 


Block  Format 


BASE  APR 

WINDOW    ID 

VIRTUAL    BASE    ADDRESS    (BYTES) 

WINDOW  SIZE  (32W    BLOCKS) 

REGION    ID 

OFFSET    IN    REGION    (32W    BLOCKS) 

LENGTH  TO  MAP    |32W    BLOCKS) 

WINDOW    STATUS    WORD 

SEND/RECEIVE    BUFFER    ADDRESS  (BYTES) 

Byti 
0()s«t 
0 


10 


12 


14 


16 


Figure  3-5  Window  Definition  Block 


These  symbols  are  defined  by  the  WDBDFS  macro,  as  described  in  Section 
3.5.2.  1. 

The  following  directives  require  a  pointer  to  a  WDB : 

Create  Address  Window  (CRAWS) 
Eliminate  Address  Window  (ELAWS) 
Map  Address  Window  (MAPS) 
Unmap  Address  Window  (UMAPS) 
Send  By  Reference  (SREFS) 
Receive  By  Reference  (RREFS) 

When  a  task  issues  one  of  these  directives,  the  Executive  clears  the 
four  high-order  bits  in  the  window  status  wc  rd  of  "-he  appropriate  WDB. 
After  completing  the  directive  operation,  the  Executive  can  then  set 
any  of  these  bits  to  tell  the  task  what  actions  were  taken.  The 
Executive  never  modifies  the  other  bits. 


3.5.2.1  Using  Macros  to  Generate  a  WDB  -  RSX-llM  provides  two  macros, 
WDBDFS  and  WDBBKS,  to  generate  and  define  a  WDB.  WDBDFS  defines  the 
offsets  and  status  word  bits  for  a  window  definition  block;  WDBBh$ 
then  creates  the  actual  window  definition  block.  The  format  of  WDBDFS 
is : 

WDBDFS 


3-17 


apr 


MEMORY  MANAGEMENT  DIRECTIVES 

Since  WDBBKS  automatically  invokes  WDBDF$,  you  need  only  bpecify 
WDBBKS  in  a  module  that  generates  a  WDB .  The  format  of  the  call  to 
WDBBKS  is: 

WDBBKS    apr,slz,rid,off,len,sts,srb 

A  number  from  0  to  7  that  specifies  the  window's  base  Active  Page 
Register  (APR).  The  APR  determines  the  4K  boundary  on  which  the 
window  Is  to  begin.  APR  0  corresponds  to  virtual  address  0,  APR 
1    to    4K,    APR    2    to    8K,    and    so    on. 

The    size   of    the   window    In    32-word    blocks. 

A   region    ID. 

."he  offset  within  the  region  to  be  mapped,  In  32-word  blocks. 

The  length  within  the  region  to  be  mapped,  in  32-word  blocks 
(defaults  to  the  value  of  siz  above). 

The  bit  definitions  of  the  window  status  word. 

A  send/receive  buffer  virtual  address. 


si  z 
rid 
off 
len 

sts 
srb 


The  argument  sts  sets  specified  bits  in  the  status  word   W.NSTS.    The 
argument  normally  has  the  following  format: 

<bltl  [ ! . . . ibitn] > 

bit 

A  defined  bit  to  be  set. 

The  macro  call 


WDBBKS 

5, 76. ,0, 50,  ,  , 

expands    to: 

.BYTE 

0,5 

.WORD 

0 

.WORD 

76. 

.WORD 

0 

.WORD 

50. 

.WORD 

0 

.WORD 

WS.MAPIWS.WRT 

.WORD 

0 

(Window  ID  returned  In  low-order  byte) 
(Base  virtual  address  returned  here) 


If  a  Create  Address  Window  directive  pointed  to  the  WDB  defined  by  the 
macro  call  expanded  above,  the  Executive  would: 

•  Create  a  window  76  (decimal)  blocks  long   beginning   at   APR  5 

(virtual  address  20K  or  120000  octal) 

•  Map  the  window  with  write  access  ( <WS. MAP! WS. WRT>)  to  the 
issuing  task's  task  region  (because  the  macro  call  specified  0 
for  the  region  ID) 
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•  Start  the  map  50  (decimal)  blocks  from  the  base  of  the  region, 
and  map  an  area  either  equal  to  the  length  of  the  window  (76 
fdeclmal]  blocks)  or  to  the  length  remaining  in  the  region, 
whichever  is  smaller  (because  the  macro  call  defaulted  the  len 
argument) 

•  Return  values  to  the  symbolic  W.NID  (the  window's  ID)  and 
W.NBAS  (the  window's  virtual  base  address) 


3.5.2.2  Using  FORTRAN  to  Generate  a  WDB  -  You  must  create  an  8-word, 
single-precision  integer  array  as  the  WDB  to  be  supplied  in  the 
subroutine  calls: 

CALL  CRAW  (Create  Address  Window  directive) 

CALL  ELAW  (Eliminate  Address  Window  directive) 

CALL  MAP  (Map  Address  Window  directive) 

CALL  UNMAP  (Unmap  Address  Window  directive) 

CALL  SREF  (Send  By  Reference  directive) 

CALL  RREF  (Receive  By  Reference  directive) 

(See  the  PDP-1 1  FORTRAN  Language  Reference  Manual  for  Information  on 
the  creation  of  arrays.)  A  WDB  array  has  the  fo\ lowi  ng  format: 


Word 

iwdb(l) 


Contents 

Bits  0  to  7  contain  the  window  ID;   bits  8   to   15 
contain  the  window's  base  APR. 


iwdb(2) 
lwdb(3) 
1  wd  b  ( 4  ) 
i  wd  b  ( 5  ) 

iwdb(6) 

i  wd  b  (  7 ) 

iwdb(8) 


Base   virtual    address   of    the    window. 

Size    of    the    window    in    32-word    blocks. 

Region    ID. 

Offset  length   within   the   region   at   which   map 
begins,  in  32-word  blocks. 

Length  mapped  within  the  region  in  32-word  blocks. 

Window  status  word  (see   the   paragraph   following 
this  1  1st)  . 

Address  of  send/receive  buffer. 


You  can  modify  the  window  status  word  lwdb(7)  by  setting  or  clearing 
the  appropriate  bits.  Soe  the  list  in  Section  3.5.2  that  describes 
the  defined  bits.  The  bit  values  are  listed  alongside  the  symbolic 
offsets . 


Note  that: 


The  contents  of  bits  8  to  15  of  Iwdb(l)  must  normally  be  set 
without  destroying  the  value  In  bits  0  to  7  for  any  directive 
other  than  Create  Address  Window. 

A  call  to  GETADR  (see  Section  1.5.1.4)  can  be  used  to  set  up 
the  address  of  the  send/receive  buffer.   For  example: 


CALL  GETADR (IWDB, ,,,,,,, IRCVB) 

This  call  places  the  address  of  buffer  IRCVB  in  array  element 
8.  The  remaining  elements  are  unchanged.  The  subroutines 
SREF  and  RREF  also  set  up  this  value.  If  you  use  the  SREF  and 
RREF  routines,  you  do  not  need  to  use  GETADR. 
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3.S.3   Assigned  Values  or  Settings 

The  exact  values  or  settings  assigned  to  individual  fields  within  the 
RDB  or  the  WDB  vary  according  to  each  directive.  Fields  that  are  not 
required  as  input  can  have  any  value  when  the  directive  Is  issued. 
Chapter  5  describes  which  offsets  and  settings  are  relevant  for  each 
memory  management  directive.  The  values  assigned  by  the  task  are 
called  input  parameters,  whereas  those  assigned  by  tne  Executive  are 
called  output  parameters. 


3.6   PRIVILEGED  TASKS 

When  a  privileged  tasK  maps  to  the  Executive  and  the  I/O  page,  '■to 
system  normally  dedicates  five  or  six  APRs  to  this  mapp  ■\ 
privileged  task  can  issue  memory  management  directives  to  rem.ir  ■■■/ 
number  of  these  APHs  to  regions.  Take  great  care  when  using  the 
directives  In  this  way,  because  such  remapping  can  cause  obscure  bugs 
to  occur.  When  a  directive  unmaps  a  window  that  formerly  mapped  the 
Executive  or  the  I/O  page,  the  Executive  restores  the  former  mapping. 

NOTE 

Tasks  should  not  remap  APRO.  It  APRO  Is 
remapped,  information  such  as  the  DSW, 
overlay  structures,  or  language  runtime 
systems  will  become  Inaccessible. 
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PARENT/OFFSPRING  TASKING 

4.1   PARENT/OFFSPRING  TASKING  liUPPORT  OVERVIEW 

Parent/of  fspr  It. q  tasking  has  many  re<il-time  applications  in 
establiahing  a:, J  controlling  complex  interrelationships  between  parent 
and  offspring  tasks.  A  parent  task  is  one  that  starts  or  connects  to 
another  task,  called  an  offspring  task.  A  major  application  for  the 
parent-offspring  task  relationship  Is  batch  processing.  When  running 
tasks  In  this  manner,  you  can  set  up  task  relationships  and  parameters 
on  line  to  control  the  processing  of  a  batch  job  (or  iot^a)  that  run 
off  1 ine . 

Starting  (or  activating)  offspring  tasks  Is  called  "spawriim." 
Spawning  also  Includes  the  ability  to  establish  task  communications; 
a  parent  task  can  be  notified  when  an  offspring  task  exits  and  can 
receive  status  Information  from  the  offspring  task. 

Status  returned  from  an  offspring  task  to  a  parent  task  Indicates 
successful  completion  of  the  offspring  task  or  'dentifies  specific 
error  cond 1 t ions . 


4. 1   DIRECTIVK  SUMMARY 

This  section  summarizes  the  directives   for   patent/offspring   taskinc; 
and  inter-task  communication. 


4.2.1   Parent/Offspring  Tasking  Directives 

There  are  two  classes  of  parent,'of  f  spr  inq  tasking  directives: 

•  Spawning  --  directives  that  create  a  connection  between  tasks 

•  Chaining  -•-  directives  that  transfer  a  connection 
Three  directives  can  connect  a  parent  task  to  an  offspring  task: 

•  Spawn  -  Vhis  directive  requests  activation   of,   and   connects 
to,  a  specific  offspring  task. 

An  offspring  task  spawned  by  a  parent  task  has  the  fallowing 
three  task  functions  that  ire  not  provided  by  thp  Request  or 
Run  directive. 
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1.   A  spawned  offspring  task  car  be  a  command  line  Interpreter 
(CLI) . 


2.  A  spawned  offspring  task  in  an  RSX-llM-PLUS  syste..!  can 
have  a  virtual  terminal  as  its  terminal  input  device 
(TI:). 

3.  A  spawned  offspring  task  can  return  current  status 
information  or  exit  status  information  to  a  connected 
parent  task  or  tasks. 

Spawn  directive  options  include: 

1.  Queuing  a  command  line  for  the  offspring  task  (which  may 
be  a  command  line  interpreter). 

2.  Establishing  the  offspring  task's  TI :  as  a  physical 
terminal,  or,  in  RSX-llM-PLUS  aybtems,  as  a  previously 
created  virtual  terminal  unit. 

3.  For  privileged  or  CLI  tasks,  designating  any  terminal  as 
the  offspring  TI: 

•  Connect  -  This  directive  estaulishes  task  cormunicat ions  for 
synchronizing  with  the  exit  status  or  emit  status  issued  by  a 
task  that  is  already  active. 

•  Send,  Request,  and  Connect  -  This  directive  sends  data  to  the 
specified  task,  requests  activation  of  the  task  if  it  is  not 
already  active,  and  connects  to  the  task. 

There  are  also  two  directives  that  support  task  chaining: 

•  Request  and  Pass  Offspring  Information  --  This  directive 
allows  an  offspring  task  to  pass  its  parent  connectior  to 
another  task  thus  making  the  new  task  the  offsoring  of  the 
original  parent.  The  RPOI$  directive  offers  all  the  options 
of  the  Spawn  directive. 

•  Send  Data,  Request  and  Pass  Offspring  Control  Block  —  This 
directive  sends  a  data  packet  for  a  specified  task,  passes  its 
parent  connection  to  that  task,  and  requests  it  if  it  is  not 
already  active. 

A  parent  task  can  connect  to  mote  than  one  offspring  task  using  the 
Spawn  and  Cor.nect  directives,  as  appropriate.  In  addition,  the  parent 
task  can  use  the  directives  in  any  combination  to  multiply  connect  to 
offspring  tasks. 

An  offspring  task  can  be  connected  to  multiple  parent  tasks.  An 
appropriate  data  structure,  the  Offspring  Control  Block,  is  produced 
(in  addition  to  those  already  present)  each  time  a  parent  task 
connects  to  the  offspring  task. 


4.2.2   Task  Communication  Directives 

Two  directives  in  an  offspring  task  return  status  to  connected   parent 
tasks : 
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•  Exit  With  Status  -  This  directive  in  an  offspring  task  causes 
the  offspring  task  to  exit,  passing  status  words  to  all 
connected  parent  trjsks  (one  or  moro)  that  have  been  previously 
connected  by  a  Spawn,  Connect,  or  Send,  Request,  and  Connect 
d  i  rei'tlve . 

•  Fmit  Status  -  This  directive  causes  the  offspring  task  to  pass 
status  words  to  either  the  specified  connected  task  or  all 
connected  parent  tasks  if  no  task  Is  explicitly  specified. 

When  status  is  passed  to  tasks  in  this  manner,  the  parent   task(s)   no 
longer  remains  connected. 

Standard  offspring  task  status  values  that  can  be  returned   to   parent 
tasks  are  listed  as  follows: 


EX$WAR 

EX$SUC 
EX$ERR 

EX$SEV 


Warning  -  task      succeeded, 
i rreguTai l t ies  are  possible 


but 


Success  -  results  should  be  as  expected 

Error  -  resul.-.s  are  unlikely   to   be   as 
expected 

Severe  Error  -  one  or  more  fatal   errors 
det»»"ted,  or  task  aborted 


These  symc^is  ere  defined  in  DIRSYM.MAC.  They  become  defined  locally 
when  the  EXST$  nacro  is  invoked.  However,  the  exit  status  may  be  any 
16-bit  value. 


4.3   CONNECTING  AND  PASSING  STATUS 

Offspring  task  exit  status  can  be  returned  to  connected  (parent) 
task(s)  by  issuing  the  Exit  With  Status  directive.  Offspring  tasks 
can  return  status  to  one  or  more  connected  parent  tasks  at  any  time  by 
Issuing  the  Emit  Status  Directive.  Note  that  only  connected 
parent-offspring  tasks  can  pass  status. 

The   means   by  which   a    task   connects    to    another  task    are 

indistinguishable   once  the  connect  process  is  complete.  For  example, 

Task  A  can  become  connected  to  Task  B  in  one  of  the  four  ways  shown 
below. 

•  Task  A  spawned  Task  B  when  Task  B  was  inactive. 

•  Task  A  connected  to  Task  B  when  Task  B  was  active. 

•  Task  A  issued  a  Send,  Request,  And  Connect  to  lask  B  when  Task 
B  was  either  active  or  inactive. 

•  Task  A  either  spawned  or  connected  to  Task  C,  which  then 
chained  to  Task  B  by  means  of  either  an  RPOI$  directive  or  an 
SDRPS  directive. 

Regardless  of  the  way  in  which  Task  A  became  connected  to  Task  'J.  Task 
B  can  pass  status  information  back  to  Task  A,  set  the  event  flag 
specified  by  Task  A,  or  cause  the  AST  specified  by  Task  A  to  occur  in 
any  of  the  five  ways  shown  below.  Note  that  once  offspring  task 
status  is  returned  to  one  or  more  parent  tasks,  the  parent  tasks 
become  disconnected. 
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•  Task  B  Issues  a  normal  (successful)  exit  directive.  Task  A 
receives  a  status  of  EX$S  IC. 

•  Task  B  is  aborted.  Task  A  receives  a  severe  error  status  ot 
EX$SEV. 

•  Task  B  issues  an  Exit  With  Status  directive,  returning  status 
to  Task  A  upon  completion  of  Task  B. 

•  Task  B  issues  an  Emit  Status  directive  specifying  Task  A.  If 
Task  A  is  multiply  connected  to  Task  B,  the  OCBs  that  contain 
information  about  these  multiple  connections  are  stored  in  a 
FIFO  queue.  The  first  OCB  is  used  to  jetermine  which  event 
flag,  AST  address,  and  exit  status  block  to  use. 

•  Task  B  issues  an  Emit  Status  directive  to  all  connected  tasks 
(no  task  name  specified). 

When  a  task  has  previously  specified  another  task  in  a  Spawn,  Connect, 
or  Send,  Request,  and  Connect  directive  and  then  exits,  ind  if  status 
has  not  yet  been  returned,  the  OCB  representing  this  connect  remains 
queued.  However,  the  OCB  is  marked  to  indicate  that  the  parent  task 
has  exited.  When  this  OCB  is  subsequently  dequeued  due  to  an  Emit 
Status  directive,  or  any  type  of  exit,  no  action  is  taken  since  the 
parent  t<isk  has  exited.  This  procedure  is  followed  to  help  a 
multiply-connected  task  to  remain  synchronized  when  parent  tasks 
unexpectedly  exit. 

Examples  of  using  directives  for  intertask  synchronization  arc 
provided  below  (macro  call  form  for  directives  are  shown).  Task  A  is 
the  parent  task  and  Task  R  is  the  offspring  task. 

Task  A     Task  B  Action 


SPWNS      EXSTS      Task  A  spawns  Task  B.    Upon   Task   B   completion. 

Task  B  returns  status  to  Task  A. 

CNCTS      EXST$      Task  A  -onnects  to  active  Task   B.    Upon   Task   B 

complet'on,  Task  B  retjrns  status  to  Task  A. 

SDRCS  RCVXS,  Task  A  sends  data  to  Task  B,  requests  Task  B  if  it 
EMSTS  is  presently  not  active,  and  connects  to  Task  B. 
Task  B  receives  the  data,  does  some  processing 
based  on  the  data,  returns  rtatus  to  Task  A 
(possibly  setting  an  event  flag  or  declaring  an 
AST),  and  becomes  disconnected  from  Task  A. 

SDRC$,     RCST$,     Task  A  sends  data  to  Task  B,  requests  Task  B  if  it 
USTP$      EMSTS      is  presently  not  active,  connects  to  Task   B,   and 

unstops  Task  B.  Task  B  becomes  unstopped  (if  Task 
B  previously  could  not  dequeue  the  data  packet), 
receives  the  data,  does  some  processing  based  on 
the  data,  and  returns  sta*-u5  to  Task  A  (possibly 
setting  an  event  flag  or  declaring  an  AST). 

SDAT$,     RCSTS      Task  a  queues  a  data  packet  for  Task  B  and  unstops 
USTPS  Task  B;   Task  B  receives  the  data. 

SPWN$      RPOIS      Task  A   spawns  Task  B.   Task  B  chains  to  Task  C  by 
SDRPS      issuing  an  RPOI$  or  an  SDRP$  directive.   Task  A  is 
now   Task   C's   parent.    Task   A   is   no   longer 
connected  to  Task  B. 


4-4 


PARENT/OPPSPRING  TASKING 


4.4   SPAWNING  SYSTEM  TASKS 


One  special  uae  of  the  Spawn  directiva  is  to  pass  a  command  line  to  a 
system  task.  You  may  use  the  Spawn  directive  to  pass  a  command  line 
to  a  command  line  Interpreter,  or  to  an  Installed  utility. 


4.4.1   Spawning  a  Command  Line  Interpreter 

Command  line  interpreters  can  be  broken  into  three  classes:   MCR,   the 
CLI  that  is  active  from  TI:,  and  all  others. 


•  To  pass  a  command  line  to  MCH,  use  the  task  name  MCH,,, 

•  To  pass  a  command  line  to  the  CLI  that  is  currently  active 
from  TI:,  use  the  task  name  CLI...  .  You  can  determine  which 
CLI  is  active  from  your  TI:   by  issuing  the  GC 1 1 $  directive. 

•  To  pa5s  a  command  to  a  specific  CLI  other  than  MCH  or  the  CLI 
active  from  TI :  ,  simply  use  that  CLI's  task  namo  in  your  Spawn 
directive.  The  task  name  of  DCL  is  ...DCL.  (.'hock  with  your 
system  manager  for  the  task  names  of  an/  usor-written  CLI's. 

•  On  RSX-llM  systems,  you  may  pas-^  a  command  to  a  specific  CLI 
only  if  the  specified  task  name  is  not  already  active.  If  the 
task  name  is  already  active,  the  Spawn  directive  will  fail. 


4.4.2   Spawning  a  Utility 

Utilities  are  generally  installed  under  task  names  of  the  form  ...tsk. 
This  convention  allows  the  utilities  to  be  invoked  as  MCR  commands. 
(See  the  RSX-1 IM/M-PLUS  MCR  Cperat  ions  Manual.) 

You  can  pass  commands  to  a  utility  in  one  of  tw-  ways.   You  can  spawn 

the   utility  directly,  using  the  task  name  ...^sk.   Or,  you  can  spawn 

MCR  and  pass  it  a  command  line  that  begins  with  rhree-character  task 
name. 


4.4.2.1  Spawning  a  Utility  under  RSX-llM  -  If  you  attempt  to  spawji 
...tsk  directly  on  an  RSX-llM  system,  the  operation  behaves  as 
follows: 

•  If  that  task  is  not  yet  active,  the  »»uecutive  will  activate 
it,  under  the  name  ...tsk. 

•  If  the  task  ...tsk  is  already  active,  your  Spawn  directive 
will  fail,  regardless  of  which  terminal  has  activated  that 
task . 

If  you  pass  MCR  a  command  line  beginning  with  "tsk",  MCR  will: 


•  Attempt  to  activate  the  task  ...tsk. 

•  If  that  task  name  is  already  active,  MCR  will  attempt  to 
activate  the  task  under  the  name  tskTnn,  where  nn  is  the  unit 
number  of  your  TI:. 

•  If  both  ...tsk  and  tskTnn  are  already  active,  MCR  will  report 
failure  to  your  task. 
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Unless  you  are  certain  that  the  utility  you  desire  Is  not  yet  active 
In  the  system,  direct  spawning  of  the  utility  offers  a  greater 
likelihood  of  failure  than  requesting  the  utility  through  MCR.  For 
this  reason,  It  is  recommended  that  on  RGX-1 IM  systems  you  request 
utilities  through  MCR. 


4.4.2.2  Spawning  a  Utility  under  RSX-UM-PLUS  -  On  RSX-UM-PLUS  sys- 
tems, whenever,  you  spawn  a  t isk  using  a  name  of  the  form  ...tsk,  the 
executive  activates  the  tark  as  tskTnn,  This  is  the  same  renaming 
procedure  used  by  MCR  under  RSX-UM-PLUS. 

On  RSX-UM-PLUS  systems,  Invoking  a  utility  through  MCR  offers  no 
advantage  over  spawning  the  utility  directly.  Further,  Invoking  the 
utility  through  MCR  incurs  extra  system  overhead.  Therefore  It  Is 
recommended  that  you  spawn  utilities  directly  on  RSX-llM-PLUS  systems. 


4.4.2.3  Passing  Command  Lines  to  Utilities  -  Rven  when  you  spawn  a 
utility  directly,  pass  a  command  line  that  include",  the  entire  command 
as  you  would  type  It  at  nhe  terminal  or  pass  It  to  MCH.  Include  the 
3-character  task  name  followed  by  a  space.  This  maintains 
compatibility  with  the  format  used  by  MCR  to  pass  commands  to 
utilities.   (See  the  description  of  the  GMCRS  directive  in  Chapter  "i .  ) 
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CHAPTER  S 
DIRECTIVE  DESCRIPTIONS 


Each  directive  description  consists  of  an  explanation  of  the 
directive's  function  and  use,  the  names  of  the  cor  respond Inq  macro  and 
FORTRAN  calls,  the  associated  parameters,  and  possible  return  values 
of  the  Directive  Status  Word  (DSW)  .  The  descriptions  generally  show 
the  S  form  of  the  macro  call  (for  Instance,  0105),  although  the  SC  and 
$S  forms  are  also  available.  Whore  the  $S  form  of  a  macro  requires 
less  space  and  performs  as  fast  as  a  DIR$  (because  of  a  small  DPB),  It 
Is  recommended.  For  these  macros,  the  texpanslon  for  the  $S  form  is 
shown,  rather  than  that  for  the  S  form. 

In  addition  to  the  directive  macros  themselves,  you  can  use  the  DIRS 
macro  to  execute  a  directive  if  the  directive  has  a  predefined  DPB. 
See  Sections  1.4.1.1  and  1.4.2  for  further  details. 


5.  1   DIRECTIVE  CATEGORIES 

For  ease  of  reference,  the  directive  descriptions  are  presented 
alphabetically  in  Section  5.3  according  to  the  directive  macro  calls. 
This  section,  however,  groups  the  directives  by  function.  The 
directives  are  grouped  into  the  following  ten  categories: 

•  Task  execution  control  directives 

•  Task  status  control  directives 

•  Informational  directives 

•  Event-associated  directives 

•  Trap-associated  directive^ 

•  I/O-  and  Intertask  rommunicat Ions-related  directives 

•  Memory  management  'iirectives 

•  Parent/offspring  tasking  directives 

•  RSX-llM-PLUS  directives 

•  Command  line  interpreter  (Cl.I)  support  directiveri 


5.1.1   Task  Execution  Control  Directives 

The  task  execution  control  directives  deal  principally  with  starting 
and  stopping  tasks.  Each  of  these  directives  (except  Extend  Task) 
results  in  a  change  of  the  task's  state  (unless  the  task  is  already  in 
the  state  being  requested).   These  directives  arc: 
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Macro  Directive  Naa* 

AbHT$  Abort  Task 

CSRO$  Cancel  Time  Based  Initiation  P-;que.st3 

EXITSS  Task  Exit  ($S  form  recommended) 

EXTK$  Extend  Task 

ROisTS  Request  Task 

RSUMS  Resume  Task 

RUNS  Hun  Task 

SPND$S  Suspend  ,SS  form  i fcommended ) 


5.1.2   Task  Status  Control  Directiv«8 

Two  task  status  control  directives  alter  the  checkpointable  .ittributf 
of  a  task.  A  third  directive  changes  the  running  priority  of  an 
active  task.   These  directives  if: 

Macro  Directive  Name 

ALTPS       Alter  Priority 

DSCPSS      Disable  Checkp<i  Int  incj  {$S  form  recommended) 

ENCP$S      Enable  Ch-  -     tlnq  (SS  form  recommended) 


5.1.3   Informational  Directives 

Several  directives  provide  the  issuing  task   with  system   information 

and   parameters   such   as:    ►he  time  of  day,  the  task  p^irameters,  the 

console  switch  settings,  and  partition  or   region  parameters.    The-.e 
directives  are: 

Macro  Directive  Nane 

GPRT$  Get  Partition  Parameters 

GREGS  Get  Region  Parameters 

GSSW$S  Get  Sense  switches  '$S  form  recommended) 

GTIMS  Get  Time  Parameters 

GTSKS  Get  Task  Parameters 


5.1.4   Event-Associated  Directives 

The  event  and  event  flag  directives  provide  inter-  ana  Intratask 
synchronization  and  signaling  and  the  means  to  set  the  system  time. 
You  must  use  these  directives  carefully  since  software  faults 
resulting  from  erroneous  signaling  and  synchronization  are  often 
obscure  and  difficult  to  isolate.   Th'>  ii  recti  ves  are: 

Macro  Directive  Name 

CLEFS  Clear  Evert  Flag 

CMKTS  Cancel  Mark  Tirtie  Requesfs 

CRGFS  Create  Group  Global  Event  Fl  agr, 

DECLSS  Declare  Significant  Event  'SS  form  recommend vd i 

ELGFS  Eliminate  Gro'in  Global  Event  Flags 

EXIFS  Exit  If 

MRKTS  Mark  Time 

RDAFS  Read    All     Event     Flags 

RDXFS  Read    Extended     Event     Flags 

SETFS  Set    Event    Fljg 

STIKS  Set    System    Tisne 
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Macro  Directive  Name 

STLO$  Stop  For  Logical  'OR'  of  Event  Flags 

STOP$S  Stop  {$S  form  recommended) 

STSE$  Stop  For  Single  Event  Flag 

ULGF$S  Unlock  Group  Global  Event  Flags  {$S  form  recommended] 

USTP$  Unstop 

WSIGSS  Walt  For  Significant  Event  ($S  form  recommended) 

WTLOS  Wait  For  Logical  OR  Of  Event  Flags 

WTSES  Wait  For  Single  Event  Flag 


5.1.5  Trap-Associated  DireCiives 

The  trap-associated  directives  provide  trap  facilities  that  allow 
transfer  of  control  (software  interrupts)  to  the  executing  tasks. 
These  directives  are: 

Macro  Directive  Name 

ASTX$S  AST  Service  Exit  ($S  form  recommended) 

DSAR$S  Disable  AST  Recognition  ($S  form  recommended) 

ENARSS  Enable  AST  Recognition  ($S  form  recommended) 

IHARSS  Inhibit  AST  Recognition  ($S  form  recommended) 

SCAA$  Specify  Command  Arrival  AST 

SFPA$  Specify  Floating  Point  Processor  Exception  AST 

SPRA$  Specify  Power  Recovery  AST 

SRDA$  Specify  Receive  Data  AST 

SREA$  Specify  Requested  Exit  AST 

SREX$  Specify  Requested  Exit  AST  (extended) 

SRRA$  Specify  Receive-By-Ref erence  AST 

SVDBS  Specify  SST  Vector  Table  For  Debugging  Aid 

SVTK$  Specify  SST  Vector  Table  For  Task 


5.1.6   I/O-  and  Intertask  Communications-Related  Directives 

The  I/O-  and  intertajk  communications-related  directives  allow  tasks 
to  access  I/O  devices  at  the  dri^'er  interface  level  or  interrupt 
level,  to  communicate  with  other  tasks  in  the  system,  and  to  retrieve 
the  MCR  command  line  used  r.o  start  the  task.   These  directives  are: 

Macro  Directive  Name 

ALUN$  Assign  LUN 

CINT$  Connect  To  Interrupt  Vector 

GLUN$  Get  LUN  Information 

GMCR$  Get  MCR  Command  Line 

QIO$  Queue  I/O  Request 

QIOWS  Queue  I/O  Request  And  Wait 

RCVD$  Receive  Data 

RCVXS  Receive  Data  Or  Exit 

SDAT$  Send  Data 

SMSG$  Send  Message 


5.1.7   Memory  Management  Directives 

The  memory  management  directives  allow  a  task  to  manipulate  its 
virtual  and  logical  address  space,  and  to  set  up  and  control 
dynamically  the  window-to-region  mapping  assignments.  The  directives 
also  provide  the  means  by  which  tasks  can  share  and  pass  references  to 
data  and  routines.   These  directives  are: 
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Macro  Directive  Name 

ATRG$  Attach  Region 

CRAWS  Create  Address  *Vindow 

CRRGS  Create  Region 

DTRG$  Detach  Region 

ELAW$  Eliminate  Address  Window 

GMCX$  Get  Mapping  Context 

MAP$  Map  Address  Window 

RREF$  Receive  By  Reference 

SREF$  Send  By  Reference 

UMAP$  Unmap  Address  Window 


5.1.8   Parent/Offspring  Tasking  Directives 

Parent/offspring  tflsking  directives  permit  tasks  to  start  other  tasks, 
and  to  connect  to  other  tasks  in  order  to  receive  status  Information. 
These  directives  are: 

Macro  Directive  Name 

CNCT$  Connect 

EMSTS  Emit  Status 

EXST$  Exit  Wit!,  Status 

RPOI$  Request  and  Pass  Offspring  Information 

SDRC$  Send,  Request  And  Connect 

SDRP$  Send  Data,  Request  and  Pass  OCB 

SPWN$  Spawn 


5.1.9   RSX-llM-PLUS  Directives 

In  addition  to   the   directives   just   listed,   RSX-llM-PLUS   Includes 

directives  that  support  virtual  terminals,  CPU/UNIBUS  affinity, 
supervisor-mode  library  routines,  variable-length  send/receive  data 
buffers,  and  parity  error  AST  routine  support.   These  directives  are: 

Macro  Directive  Nane 

CPCR$  Checkpoint  Common  Region 

CRVTS  Create  Virtual  Terminal 

ELVT$  Eliminate  Virtual  Terminal 

MSDS$  Map  Supervisor  D-Space 

MVTSS  Move  to/from  I/D-Space 

RDEFS  Read  Single  Event  Flag 

RMAF$S  Remove  Affinity  ($S  form  only) 

SCAL$S  Supervisor  Call  ($s  form  only) 

SPEAS  Specify  Parity  Error  AST 

SNXC$  Send  Next  Command 

STAF$  Set  Affinity 

VRCD$  Variable  Receive  Data 

VRCS$  Variable  Receive  Data  Or  Stop 

VRCX$  Variable  Receive  Data  Or  Ex  * c 

VSRC$  Variable  Send,  Request,  and  Connect 

VSDAS  Variable  Send  Data 
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These  functions  provide  for  the  dispatching  of  multiuser  tasks  and  can 
enhance  the  Interface  to  slave  tasks. 

The  dispatching  algorithm  used  by  the  Executive  Is  identical  to  the 
algorithm  used  by  MCR.  Thus,  the  ability  to  dispatch  copies  of 
multiuser  tasks  is  available  at  both  the  MCR  command  and  Executive 
directive  level.  A  consistent  scheme  for  rommunlcat ion  and 
synchronization  between  multiuser  tasks  Is  made  available  at  the 
Executive  level. 

Executive-level  dispatching  uses  the  same  naming  scheme  as  is  used  in 
the  RSX-llM-PLUS  MCR  dispatching  algorithm.  A  single  copy  of  the 
multiuser  task  must  be  Installed  with  a  name  of  the  form  ...mmm.  When 
a  task  Issues  a  directive  specifying  a  task  name  of  the  forn.  ...mmm, 
the  Executive  first  forms  the  task  name  mmmtnn,  where  t  is  the  first 
character  of  the  device  name  of  the  TI:  of  the  Issuing  task,  and  nn 
is  the  unit  number.  The  Executive  then  attempts  to  perform  the 
directive  as  if  the  task  name  mmmtnn  has  been  specified.  If  the 
directive  is  one  that  could  activate  the  task  (Request,  Spawn,  or 
Send,  Requfst  And  Connect),  a  TCB  may  be  dynamically  created  and 
filled  in  from  the  ...mmm  TCB.  If  the  directive  is  a  send  user-type 
directive,  and  the  TCB  n.mmtnn  does  not  exist,  the  send  packet  is 
queued  to  the  ...mmm  TCB  until  mmmtnn  is  activated.  At  that  time  any 
send  packets  for  mmmtnn  thr»t  are  queued  to  the  ...mmm  TCB  are  moved  to 
the  mmmtnn  TCB. 

This  allows  for  the  specification  of  a  specific  copy  of  a  multi-user 
task  In  a  directive  whose  TI:  is  different  from  that  of  the  issuing 
task.  If  the  TI :  of  the  target  task  Is  known,  the  task's  name  can  be 
calculated  and  explicitly  specified  in  a  directive. 


5.1.10   CLI  Support  Directives 

The  CLI  support  directives  allow  CLI  tasks  to  get  command  lines, 
request  and  pass  offspring  information,  get  command  Interpreter 
Information,  and  set  a  specified  CLI  for  a  terminal.  These  directives 
are : 

Macro  Directive  Name 

GCCIS  Get  Command  for  Command  Interpreter 
GC 1 1  $  Get  ''^.->T^^nd  Interpreter  Information 
SCLIS       Set  '.■oi-.-.-and  Line  Interpreter 


5.2   DIRECTIVE  CONVENTIONS 

The  following  are  convent  i  or.s  for  usinq  system  directives: 

1.   In  MACRO-Il  prograns,   anless   ^   number   is   followed   by   ri 
decimal  point  (.),  the  system  assumes  the  number  to  be  octal. 

In  FORTRAN  pn^jr^ms,  'jse  IMTr:GER*2  type  unless  the   dirertive 
description  states  .otherwise. 
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2.  In  MACRO-11  programs,  task  and  partition  names  can  be  from 
one  to  six  characters  long  and  should  be  represented  as  two 
words  In  Rfldlx-50  form. 

In  FORTRAN  programs,  specify  task  .ind  partition  names  by  a 
variable  of  type  RFAL  (single  precision)  that  contains  the 
task  or  partition  name  In  Radlx-50  form.  To  establish 
Radlx-50  representation,  either  use  the  DATA  statement  at 
compile  time,  or  use  the  IRAD50  subprogram  or  RAD50  function 
at  run  time. 

3.  Device  names  are  two  characters  long  and  are  represented  by 
one  word  of  ASCII  code. 

4.  Some  directive  descriptions  state  that  a  certain  parameter 
must  be  provided  even  though  the  system  Ignores  It.  Such 
parameters  are  Included  to  maintain  compatibility  between 
RSX-llM,  RSX-llM-PLUS,  ind  IAS. 

5.  In  the  directive  descriptions,  square  brackets  ([  ))  enclose 
optional  parameters  or  arguments.  To  omit  optional  Items, 
either  use  .sn  empty  (null)  field  in  the  parameter  list  or 
omit  a  trailing  optional  parameter. 

6.  Logical  Unit  Numbers  (LUNs)  can  range  from  1  to  255(10). 

7.  Event  flag  numbers  range  from  1  to  96(10).  Numbers  from  1  to 
32(10)  denote  local  flags.  Numbers  from  33  to  64  denote 
common  flags.  Numbers  65  to  96  denote  group-global  event 
flags. 

Note  that  the  Executive  preserves   all   task   registers   when   a   task 
issues  a  directive. 


5.3   SYSTEM  DIRECTIVE  DESCRIPTIONS 

Each  directive  description  includes   most   or   all   of   th*-   following 
elements : 

Name : 

This  describes  the  function  of  the  directive. 

FORTRAN  Call : 

This  shows  the  FORTRAN  subroutine  call,  and  defines  each 
parameter  . 

Macro  Cal 1  : 

This  shows  the  macro  call,  defines  each  parameter,  and  gives  the 
defaults  for  optional  parameters  in  parentheses  following  the 
definition  of  the  parameter.  Since  zero  is  supplied  for  most 
defaulted  parameters,  only  nonzero  default  values  are  shown. 
Parameters  ignored  by  RSX-1 IM/M-PLUS  are  required  for 
compatibility   with    IAS. 
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Macro  Expansion 


Definition  Block  Parameters: 

Only  the  memory  management  directive  descriptions  Include  these 
parameters.  This  section  describes  all  the  relevant  input  and 
output  parameters  in  the  Region  or  Window  Definition  Block  (see 
Section  3.5). 

Local  Symbol  Definitions: 

Macro  expansions  usually  generate  local  symbol  definitions  with 
an  assigned  value  equal  to  the  byte  offset  from  the  start  of  the 
DPB  to  the  corresponding  DPB  element.  This  section  lists  these 
symbols.  The  length  in  bytes  of  the  element  pointed  to  by  the 
symbol  appears  in  parentheses  following  the  symbol's  description. 
Thus : 

A.BTTN   --   Task  name  (4) 

defines  A.BTTN  as  pointing  to  a  task  name  In  the  Abort  Task  DPB ; 
the  task  name  has  a  length  of  four  bytes. 

DSW  Return  Code: 

This  section  lists  all  valid  return  codes'. 

Notes : 

The  notes  preser.ted  with  some  directive  descriptions  expand  on 
the  function,  use,  and/or  consequences  of  using  the  directives. 
Always  read  the  notes  carefully. 
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ABRTS 

5. 3. 1   Abort  Task 

The  Abort  Task  directive  Instructs  the  system  to  terminate  the 
execution  of  the  In-^i'^atefl  task.  ABRTS  is  Intended  for  use  as  an 
emergency  or  fault  exit.  ABRTS  displays  a  termination  notification 
based  on  the  described  condition,  at  one  of  the  following  termlnala: 

1.  The  terminal  from  which  the  aborted  task  was  requested 

2.  The  originating  terminal  of  the  task  that  requested  the 
aborted  task 

3.  The  operator's  console  (CO:)  if  the  task  was  started 
Internally  from  another  task  by  a  Run  directive,  or  by  an  MCH 
or  DCL  Run  command  that  specified  one  or  more  time  parameters 

On  systems  without  multiuser  protection,  a  task  may  abort  any  task, 
Incl'jdlng  Itself.  When  a  task  Is  aborted.  Its  state  changes  from 
active  to  dormant.  Therefore,  to  reactivate  an  aborted  task,  a  task 
or  an  operator  must  request  it. 

In  systems  that  support  multiuser  protection,  a  task  must  be 
privileged  to  issue  the  Abort  Task  directive  (unless  it  is  aborting  a 
task  with  i-.he  same  T!:). 

FORTRAN  Cal 1 : 

CALL  ABORT  (t3k[  ,ld3l  ) 

tsk   3   Name  of  the  task  to  be  aborted  (RAD50) 

ids   =   Directive  status 

Macro  Cal 1 : 

ABRTS    tJk 

tsk   =   Name  of  the  task  to  be  aborted  'RAD5C) 

Macro  Expansion: 

ABRTS    ALPHA 

.BYTE    83.,  3  ;ABRTS  MACRO  DIC,  DPB  SIZF:=«3  WORDS 

.RAD50   /ALPHA/  ;TA5K  "ALPHA" 

Local  Symbol  Definitions: 

A.BTTN    -   Task  name  '4) 
DSW  Return  Codes: 

IS. sue   --   Successful  completion 

IE.  INS   --   Task  not  installed 

IE. ACT   --   Task  not  active 
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lE.PRI       --      l33uln>j    tasK    is    not    privileged    (mul  1 1  user 
protection    systems  only) 

lE.ADP      --      Part    of      the    DPB    Is   out    o£    the    Issuing    taak's    ai 
space 

lE.SDP      --      Die   or    DPB    size    Is    Invalid 


Notes ; 


1. 


2, 


When    a    task    Is    aborted,    the    Executive 
asources.       In    parthjlar,    the    Executive: 


all       the      task's 


Detaches   all    attached    devices. 

Flushes    the    AST  queue    and    deapeclf: 

Flushes    the    receive    and    recelve-by-ref er ence    queue. 

Flushes    the    clock    queue    for    outstanding    Mark    Time    requ. 
for    the    task. 

Closes    all    open    files    (files   open      for      write       i      ■• 
locked) . 


are 


Detaches  all  attached  regions  except  In  the  •  t  ,.•  of  a 
fixed    task,    where    no    detaching    occurs. 

Runs   down    the    task's    -/O. 

Deaccesses  the  group  global  event  flags  for  the  task's 
group. 

Disconnects  from  interrupts. 

Flashes  all  outstanding  CLI  command  buffe.'s  for  the  task. 

Breaks  the  connection  with  any  offspring  tasks. 

Returns  a  severe  error  status  fEXSSEV)  to  the  parent  task 
when  a  connected  task  is  aborted. 

Marks  virtual  terminals  created  by  the  aborted  task  for 
deallocation.  The  virtual  terminals  actually  become 
deallocated  whf  \  all  tasks  using  the  virtual  terminal{s) 
are  aborted  or  exit  (  ;ee  Section  4.2).  Nonpr Iv I leged 
tasks  using  virtual  terminal  units  that  are  marked  for 
deallocation  as  TI:   are  also  aborted. 

e   Frees  the  task's  nenory  If  the  aborted  task  was  not  fixed. 

If  the  aborted  task  had  a  requested  exit  AST  specified,  the 
task  will  receive  that  AST  instead  of  being  aboited.  No 
indication  that  this  has  occurred  Is  returned  to  the  task 
that  Issued  the  abor".  request. 

When  the  aborted  task  actually  exits,  the  Executive  declares 
a  significant  event. 
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ALTP$ 


5. 3. 2  Alter  Priority 

The  Alter  Priority  directive   instructs   the   system   to  change   the 

running   priority  of  .t  specified  active  task  to  either  a  new  priority 

indicated  in  the  directive  call,  or  the  task's  default  (installed) 
priority  if  the  call  does  not  specify  a  new  priority. 

The  specified  task  must  be  installed  and  active.  The  Executive  resets 
the  task's  priority  to  Its  Installed  priority  when  the  task  exits. 

If  the  directive  call  omits  a  task  name,  the  Executive  defaults  to  the 
Issuing  task. 

The  Executive  reorders  any  outstanding  I/O  requests  for  the  task  in 
the  I/O  queue  and  reallocates  the  task's  partition.  The  partition 
reallocation  may  cause  the  task  to  be  checkpo  Inted . 

In  systems  that  support  multiuser  protection,  a  non-pr 1 vlleged  task 
can  issue  ALTP$  only  for  Itself,  and  only  for  a  priority  equal  to  or 
lower  than  its  installed  priority.  A  privileged  task  can  change  the 
priority  of  any  task  to  any  value  less  than  250. 

FORTRAN  Call  : 

CALL  ALTPRI  ( [  tsk J  , [  Ipr 1 ]  I  ,  ids]  ) 

tsk    =  Active  task  name 

Ipri   =   A  1-word  integer   value   equal  to   the  new  priority, 
a  number  from  1  to  250  (decimal) 

ids    =   Directive  status 

Macro  Call  : 

ALTPS   [tsk]  r  ,pri] 


tsk 
pri 

Macro    Expansion 


Active    task   name 

New   priority,    a    number    from    1    to    250    (decimal) 


ALTPS 

ALPHA,  75. 

•  BYTE 

5.,  4 

.RAD50 

/ALPHA/ 

.WORD 

75, 

AL-^PS    MACRO    Die,     DPB    SIZJ=4    WORDS 
TASK    ALPHA 
NEW    PRIORITY 


Local    Symbol    Definitions; 

A.LTTN      --      Task   name    [4) 
A.LTPR      --      Priority    (2) 
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DSW  Return  Codes: 

IS. sue   ~  Successf'jl  completion. 

IE.  INS   —   Task  not  Ini^talled. 

IE. ACT   --   Task  not  active. 

IE. PHI   —   Issuing   ta:ik  is  not  privileqed  (ly-'tiuser  protection 
systems  only) . 

lE.IPR   —   Invalid  priority. 

lE.ADP   —   Part  of  the  DPB   is  out  of  the  issuing  task's  address 
space . 

lE.SDP  —   Die  or  DPB  size  is  invalid. 
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S. 3. 3   Assign  LUN 

The  Assign  LUN  directive  instructs  the  system  to  assign  a  physic;»l 
device  unit  to  a  logical  unit  number  (LUN).  It  does  not  indicate  that 
the  task  has  attached  itself  to  the  device. 


The  actual 

phys  I 

cal  device  ass 

Igned 

to  the 

log 

leal  unit   Is   depen 

dent 

on   the   1 

og  ical 

assi-inment 

table 

(see 

the 

Assign   command  In 

the 

RSX-llM/M- 

PLUS  MCR  Operations 

Manual 

or 

the 

RSX-UM/M-PLUS   Command 

Language 
(■assignment 

Reference  Manual)  . 

The  Ex 

ecutlve  first  searches  the  log 

leal 

table 

for  a  device 

name  match. 

If 

It  finds   a   match, 

the 

Executive 

ass  Ig 

i,s   the   physl 

cal   d 

ev  ice 

unit   associated   with 

the 

matching  entry  to  the  logical 

un  1 1 . 

Otherwise 

,  the  Executive  searches 

the  physical  dev 

ice  tables  and 

assig 

ns  the 

actual  physical  device 

unit 

named   to 

the 

logical   unit. 

In 

systems 

that   support   multl 

user 

protection 

,  the 

Executive  does 

not  searcli 

the 

logical  assignment  table 

if  the  task  has 

been  Installed 

with 

the  si 

ave 

option  (/SLV=YES) . 

When  a  task  reassigns  a  LUN  from  one  device  tc  another,  the  Executive 
cancels  all  I/O  requests  for  the  Issuing  task  in  the  previous  device 
queue . 

FORTRAN  Call  : 

CALL  ASNLUN  ( 1 un ,dev , un t [ , Ids) ) 

lun   =   Logical  unit  number 

dev   =   Device  name  (format:   1A2) 

unt   =   Device  unit  number 

Ids   =   Dlrec:tive  status 
Macro  Cal 1  : 

ALUNS  lun, dev, unt 

lun   =   Logical  unit  number 

dev   =   Device  name  (two  characters) 

unt   =   Device  unit  number 

Macro  Expansion: 

ASSIGN    LOGICAL    UNIT    NUMBER 
ALUNS    MACRO    DIC,     DPB    SIZE=4    WORDS 
LOGICAL    UNIT    NUMBER    7 
DEVICE    NAME    IS    TT     (TERMINAL) 
DEVICE    UNIT    NUMBER=0 

Local    Symbol  Definitions: 

A. LULU  —      Logical    unit    number    (2) 

A.LUNA  --      Physical    device    name    (2) 

A.LUNU  --      Physical    device    unit    number    (2) 


« 


ALUNS 

7 , TT , 0 

.BYTE 

7,4 

.WORD 

7 

.ASCII 

/TT/ 

.WORD 

0 

« 
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DSW  Return  Codes:  :.    , 

IS. sue   —   Successful  completion. 

lE.LNL   —   LUN  usaqe  Is  Interlocked  (see  Note  1  below). 

lE.IDU   --   Invallfl  device  and/or  unit. 

lE.ILU   --   Invalid  logical  unit  number. 

lE.ADP   —   Part  of   the  DPB  Is  out  of  the  Issuing  task's  address 
space . 

lE.SDP   --   DIG  or  DPB  size  is  Invalid. 


Notes : 


A  return  code  of  lE.LNL  Indicates  that  the  specified  LUN 
cannot  be  assigned  as  directed.  Either  the  l.UN  is  already 
assigned  to  a  device  with  a  file  open  for  that  LUN,  or  the 
LUN  Is  currently  assigned  to  a  device  attached  to  the  task, 
and  the  directive  attempted  to  change  the  LUN  assignment.  If 
a  task  has  a  LUN  assigned  to  a  device  and  the  task  has 
attached  the  device,  the  LUN  can  be  reassigned,  provided  that 
the  task  has  another  LUN  assigned  to  the  same  device. 

In  RSX-llM-PLUS  systems,  physical  I/O  (output)  operations 
should  not  be  executed  with  spooled  devices.  Output  should 
be  performed  using  File  Control  Services  (PCS). 
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ASTXS 

5.T.4   AST  Service  Exit  ($S  form  recommendeti) 

The  AST  Service  Exit  directive  instructs  •  I -•  iystem  to  terminate 
execution  of  an  AST  service  routine. 

IE  another  AST  Is  queued  and  ASTs  are  not  disabled,  then  the  Executive 
Immediately  effects  the  next  AST.  Otherwise,  the  Executive  restores 
the  task's  pre-AST  state.   See  Notes  below. 

tOHTRAN  Call ! 

Neither  the  FORTRAN  language  nor  the  ISA  standard  permits  direct 
linking  to  system  trapping  mechanisms;  therefore,  this  directive 
Is  not  available  to  FORTRAN  tasks. 

Macro  Call  : 

ASTX$S  [err] 

prr   =   Error  routine  address 

Macro  Expansion: 

ASTX$S   ERR 

MOV  (PC)+,-(SP)  ;PUSH    DPD    ONTO    THE    STACK 

.BYTE  115.,  1  ;ASTX$S    MACRO    DIG,     DPB    SIZE=1    WORD 

EKT  377  ;TRAP   TO    THE    EXECUTIVE 

JSR  PC, ERR  ;CALL    ROUTINE    "ERR"     IF    DIRECTIVE 

/UNSUCCESSFUL 

Local  Symbol  Definitions: 

None 
DSW  Return  Codes: 

IS. sue   --   Successful  completion. 

IE. AST   —   Directive  not  Issued  from  an   AST  service 
routine  . 

lE.ADP   --   Part  of  the  DPB  or  stack  is  out  of  the  Issuini  trisk's 
address  splice. 

lE.SDP   —   Die  or  DPB  size  is  invalid. 

Notes  : 

1.  A  return  to  the  AST  service  routine  occurs  if,  and  only  if, 
the  directive  is  rejected.  Therefore,  no  Branch  on  Carry 
Clear  instruction  is  generated  if  an  error  routine  addresf;  is 
given.   (The  return  occurs  only  when  the  Carry  bit  is  not.) 

2.  When  an  AST  occurs,  the  Executive  pushes,  at  minimum,  the 
following  information  onto  the  task's  stack: 

SP+05  --  Event  flag  mask  word 

SP+04  —  PS  of  task  prior  to  AST 

SP+02  --  PC  of  task  prior  to  AST 

SP+00  —  DSW  of  task  prior  to  AST 
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The  task  stack  must  be 
directive  Is  executed. 


In  this  atat*  when  the  AST  Service  Exit 


In  addition  to  the  data  parameters,  the  Executive  pushes 
supplemental  Information  onto  the  task  stack  for  certain  ASTs . 
For  I/O  completion,  the  stack  contains  the  address  of  the  I/O 
status  block;  for  Mark  Time,  the  stack  contains  the  Event 
Flag  Number;  for  a  floating-point  processor  exception,  the 
stack  contains  the  exception  codf>  and  address. 

These  AST  parameters  must  be  removed  from  the  task's  stack 
prior  to  Issuing  an  AST  exit  directive.  The  following  example 
shows  how  to  remove  AST  parameters  when  a  task  uses  an  AST 
routine  on  I/O  completion: 


Example : 


EXAMPLE  PROGRAM 
LOCAL  DATA 


lOSB: 
BUFFER: 


,BLKW 
,BLKW 


2 
30. 


;I/0  STATUS  DOUBLEWORD 
;I/0  BUFFER 


; 

;  START  OF  MAIN  PROGRAM 
J 

START:   , 


; PROCESS  DATA 


QIOWSC    lO.WVB, 2,1,, I 0SB,ASTSER,< BUFFER, 60. ,40> 

; PROCESS  &  WAIT 
EXITSS  ;EX;T  TO  £XECUTIVE 


;  AST  SERVICE  ROUTINE 

; 

ASTSER: 


; PROCESS  AST 


TST      (SP)  + 
ASTXSS 


; REMOVE  ADDRESS  OF  I/O  STATUS  BLOCK 
;AST  EXIT 


The  task  can  al'ier  its  return  address  by  manipulating  the 
information  on  its  stack  prior  to  executing  an  AST  exit 
directive.  For  example,  to  return  to  task  state  at  an 
a'Jdress  other  than  the  pre-AST  sddress  indicated  on  the 
stack,  the  task  can  simply  replace  the  PC  word  on  the  stack. 
This  procedure  may  be  useful  In  those  cases  in  which  error 
conditions  are  discovered  in  the  AST  routine;  but  you  should 
use  extreme  caution  when  doing  this  alteration  since  AST 
service  routine  bugs  are  difficult  to  isolate. 

Because  this  directive  requires  only  a  1-word  DPB,  the  $S 
form  of  the  macro  is  recommended.  It  requires  less  space  and 
executes  with  the  same  speed  as  the  DIRS  macro. 
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S.  3.  5   Attach  Reql'>n 

The  Attach  Region  directive  attaches  the  Issuing  task  to  a  static 
common  region  or  to  a  named  dynamic  region.  (No  other  type  of  rrg  Ion 
can  be  attached  to  Mi*'  ►■  i3'<  by  means  of  this  directive.)  The  Executive 
checks  the  desired  specified  In  the  region  status  word  against 
the  owner  UIC  and  t;.,  ,-;  -section  word  of  the  region.  If  there  Is  no 
protection  violation,  the  Executive  grants  the  desired  access.  If  the 
region  is  successfully  attached  to  the  task,  the  Executive  returns  a 
16-blt  region  ID  (In  R.GID) ,  which  the  task  uses  In  subsequent  mapping 
direct  Ives . 

You  can  also  use  the  directive  t  rmlnt»  the  ID  of  a  region  already 
attached  to  the  task.  In  thi.  i.  ,  the  task  specifies  the  n.ime  of 
the  attached  region  In  R.GNAM  and  clears  all  four  bits  described  below 
In  the  region  status  word  R.GSTS.  When  the  Executive  processes  the 
directive,  It  checks  that  the  named  region  Is  attached.  If  the  region 
Is  attached  to  the  issuing  task,  the  Executive  returns  the  region  ID, 
as  well  as  the  region  size,  for  the  task's  first  attachment  to  'he 
region.  You  may  want  to  use  the  Attach  Region  directive  in  this  way 
to  determine  the  region  ID  of  a  common  block  attached  to  the  task  at 
task-build  time. 

FORTRAN  Call : 

CALL  ATRG  (lrdb[ ,ld3l ) 

Irdb   «   An  8-word  Integer  array  containing  a  Region  Definition 
Blork  (see  Section  3.S.1.2) 

Ids    =   Directive  status 

•^  :  :    -all  : 

ATRGS    rdb 

rdb      =      Region    Definition    Block    address 

Macro    Expansion: 

ATRGS         RDBADR 

.BYTE  57., 2  ;ATRGS    MACRO    DTC,     DPB    SIZE-2    WORDS 

.WORD         P.DBADR  ;RDB    ADDRESS 

Region    Definition    Block    Parameters: 

Input    parameters: 

Array  Offset 

Element 

lrdb(3)M)    R.GNAM       --      Name    of    the    region    to    be    attached 

irdb(7)  R.GSTS      --      Bit      settings  '     in    the      region    status    word 

(specifying    desired    access    to    the    region): 


1.     If    you      are      a       FORTRAN      programmer,       refer       to      Section       3.S.1       to 
determine    the    bit    values    represented    by   the    symbolic    names   described. 
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Output  parameters 

irdb(l)      R.GID 


Bit  Definition 

RS.RED  —  1  if  read  access  Is  desired 

PS.WRT  —  1  if  write  access  Is  desired 

RS.EXT  —  1  If  extend  access  Is  desired 

RS.DEL  —  1  if  dele'-e  access  is  desired 

Cl*uir  all  four  bits  to  request  the  region 
ID  of  the  named  region  If  It  Is  already 
attached  to  the  Issuing  task. 

ID  assigned  to  the  region 


lrdb(2)      R.GSIZ   —   Size  in  32-word  blocks  of  the  attached 

region 

Local    Symbol    Definition: 

A.TRBA      --      Region   definition   block   address    (2) 

DSW    Return    Codes: 

IS. sue      —      Successful    completion. 

lE.UPN      —     An    attachrrent   descriptor    rannot    be   allocated. 

lE.PRI      —      Privilege   violation. 

I3.NVR      —      Invalid    region    ID. 

Specified    region    name  does   not    exist. 

-     Region   had    parity  error   or   load    failure.^ 


lE.PNS 
lE.HWR 
IF.ADP 


lE.SDP 


—     Part      of   the    DPB   or      RDB    Is   out   of   the    Issuing    task's 
address   space. 

--      Die   or    DPB   size    Is    Invalid. 


5-17 


DIRECTIVE  DESCRIPTIONS 


CINT$ 


5.3.6  Connect  to  Interrupt  Vector 

The  Connect  tn  Interrupt  Vector  direct've  •nablcs  a   task   to  process 

hardware  interrupts  through  a  specified  vector.   The  Interrupt  Service 

Routine  (ISR)  Is  Included  In  the  task's  own  space.  In  a  mapped 
systi^tn,  che  issuing  task  must  be  privileged. 

The  overhead  entails  the  execution  of  about  10  Instructions  before 
entry  into  the  ISR,  and  10  Instructions  after  exit  from  the  It>R.  The 
Executive  provides  a  mechanism  for  transfer  of  control  from  the  ISR  to 
task-level  code,  using  either  an  AST  or  a  local  event  flag. 

After  a  cask  has  connected  to  an  interrupt  vector,  It  can  process 
interrupts  on  three  different  levels:  Interrupt,  fork,  and  task.  The 
task  level  may  be  subdivided  into:   AST  level  and  non-AoT  level. 

1.  Interrupt  Level 

When  an  Interrupt  occurs,  control  is  transferred,  with  the 
Interrupt  Transfer  Block  (ITB)  that  has  been  allocated  by  the 
CINT$  directive,  to  the  Executive  subroutine  $INTSC.  From 
there  control  goes  to  the  ISR  specified  in  the  directive. 

The  ISR  processes  the  interrupt  and  either  dismisses  the 
interrupt  directly  or  enters  fork  level  through  a  call  to  the 
Executive  routine  $F0RK2. 

2.  Fork  Level 

The  fork-lovel  routine  executes  at  priority  0,  the  lowest 
processor  priority,  allowing  interrupts  and  more 
time-dependent  tasks  to  be  serviced  promptly.  If  required, 
the  fork  routine  sets  a  local  event  flag  for  the  task  and/or 
queues  an  AST  to  an  AST  routine  specified  in  the  directive. 

3.  Task  Level 

At  task  level,  entered  as  the  result  of  a  local  event  flag  or 
an  AST,  the  task  does  final  Interrupt  processing  and  has 
access  to  Executive  directives. 

Typically,  the  ISR  does  the  minimal  processing  required  for  an 
interrupt  and  stores  information  for  the  fork  routi  e  or  task-level 
routine  in  a  ring  buffer.  The  fork  routine  is  entered  after  a  number 
of  interrupts  have  occurred  as  deemed  necessary  by  the  ISR,  and 
further  condenses  the  information.  Finally,  the  fork  routine  wakes  up 
the  task-level  code  for  ultimate  processinf]  that  requires  access  to 
Executive  directives.  The  fork  level  may,  however,  be  a  transient 
stage  from  ISR  to  task-level  code  without  doing  any  processing. 

In  a  mapped  system,  a  task  must  be  built  privileged  in  order  to  be 
able   to   use   the   CINTS   directive.   However,  it  i: 


s  legal  to  use  the 


table   file 
Builder . 
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As  will  be  described  later,  In  a  mapped  system,  special  considerations 
apply  to  the  mapping  of  the  ISR,  fork  routine,  and  enable/disable 
routine  as  well  as  all  task  data  buffers  accessed  hy  these  routines. 

FORTRAN  Call : 

Not  supported 
Macro  Cal 1  : 

CINT$   vec,base, Isr ,ed i r ,pr i ,ast 

vec  ■  Interrupt  vector  address  --  Must  be  in  the  range  60(8) 
to  highest  vector  specified  during  SYSGEN,  Incljsive, 
and  must  be  a  multiple  of  4. 

base  =  Virtual  base  address  for  kernel  APR  5  mapping  of  the 
IGR,  and  enable/disable  interrupt  routines  --  This 
address  is  automatically  truncated  to  a  32(10)-word 
boundary.  The  "base"  argum«!nt  is  ignored  in  an 
unmapped  system. 

Isr  "  Virtual  address  of  the  ISR,  or  0  to  disconnect  from 
the  Interrupt  vector 

ed i r   *  Virtual   address  cf   the   enable/disable   interrupt 

routine 


pri  =  Initial  prio 
execute  --  Thi 
interrupt  prio 
where  n  is  a 
the  value  in  b 
the  programme 
and  PR7  for  th 
the  macro  HW 
programmer  sho 
value  for  t 
priority  (for 
that  interrupt 


rity   at 

s   IS   no 

rity,  and 

number  in 

its  5-7  0 

r  make  us 

is  purpos 

DDFS  foun 

uld  take 

his   para 

example , 

s  at  PR 5) 

which    the    ISR    is     to 

rmally  equal  to  the  hard-wired 

Is  expressed  in  the  form  n*40, 

the  range  0-7.   This  form  puts 

f  pr  I  .   It  Is  recommended   that 

e  of  the  symbols  PR4,  PR5,  PR6, 

e.   These  are   Implemented   via 

d  in  (1, IJEXEMC.MLB.   Also,  the 

care   to   specify  the  correct 

meter.   An   incorrect   Initial 

specifying   PR4   for   a   device 

may  result  in  a  system  crash. 


ast    =   Virtual  address  of  an  AST  routine  to  be  entered 
the  fork-level  routine  queues  an  AST 


after 


To  disconnect  from  interrupts  on  a  vector,  the  argument  Isr  Is  set 
0  and  the  arguments  base,  ed i r ,  psw,  and  ast  are  Ignored. 


to 


Macro  Expansion: 


CINTS 

420, BA 

.BYTE 

129.  ,7 

.WORD 

420 

•  WORD 

BADR 

.WORD 

lADR 

.WORD 

EDADR 

.BYTE 

?R5,  0 

.WORD 

ASTADR 

4 20, BADR, TADR, EDADR, PR  5, ASTADR 


;CINT$  MACRO  DIC,  DPB  SIZE  =  7  WORDS 

; INTERRUPT  VECTOR  ADDRESS  =  420 

.-VIRTUAL  BASE  ADDRESS  FOR  KERNAL  APR 

/VIRTUAL  ADDRESS  OF  THE  INTERRUPT 

.-SERVICE  ROUTINE 

.-VIRTUAL  ADDRESS  OF  THE  INTERRUPT 

.-ENABLE/DISABLE  ROUTINE 

.-INITIAL  INTERRUPT  SERVICE  ROUTINE 

.-PRIORITY  (LOW  BYTE).   (HIGH  BYTE  = 

/VIRTUAL  ADDRESS  OF  AST  ROUi'INE 


0.) 
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Local  .Symbol  Definitions: 

C.INVE  --  Vector  address  (2) 

C.INBA  --  Base  address  (2) 

C. INIS  --   ISR  address  (2) 

CINDI  —   Enable/dis.ible  Interrupt  routine  address  (2) 

C.INPS  --   Priority  (1) 

C. INAS  --   AST  address  (2) 
DSW  Return  Codes: 

lE.UPN  —   An  ITS  could  not  be  allocated  (no  pool  apace). 

IE. ITS  --  The  function  requested  Is  "disconnect"  and  the  task 
Is  not  the  owner  of  the  vector. 

lE.PRI  --  Issuing  task  is  not  prlvUec^ed  (not  applicable  in 
unmapped  system) . 

lE.RSU   —   The  specified  vector  Is  already  In  ufse . 

lE.ILV  —  The  specified  vector  Is  illegal  (lower  than  60  or 
higher  than  highest  vector  specified  during  SYSGEN, 
or  not  a  multiple  of  4). 

IE. MAP  —  ISR  jr  enable/disable  interrupt  routine  Is  not  within 
4i-  words  from  the  value  (base  address  (,    177700)  . 

lE.ADP  —  Part  of  the  DPB  is  out  of  the  Issuing  task's  address 
space . 

lE.SDP   --   DIG  or  DPB  size  is  Invalid. 

Notes  : 

1.  Checkpointable  Tasks 

The  following  points  should  be  noted  for  checkpointable  tasks 
onl  y : 

When  a  task  connects  to  an  interrupt  vector,  checkpointing  of 
the  task  is  automatically  disabled. 

When  a  task  disconnects  from  a  vector  and  is  not  connected  to 
any  other  vector,  checkpointing  of  the  task  Is  automatically 
enabled,  regardless  of  its  state  before  the  first  connect,  or 
any  change  In  state  while  the  task  was  connected. 

2.  Mapping  Considerations 

In  an  unmapped  system,  the  argument  "base"  is  ignored,  and 
the  arguments  "isr,"  "edir,"  and  "ast"  are  physical 
addresses . 

In  a  mapped  system,  however;  the  argument  "base,"  after 
being  truncated  to  a  32(10)-word  boundary,  is  the  start  of  a 
4K-word   area  mapped  in  kernel  APR  5.    All  code   and  data  in 
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the  task  thot  Is  ujed  by  the  routlnas  nust  fall  within  that 
araa,  or  a  fatal  error  will  occur*  probably  raaultlng  In  a 
system  crash. 

Furthermore,  the  code  and  data  must  be  either  position 
Independent  (refer  to  the  PDP-1 1  MACRO- l 1  Language  Reference 
Manual  for  more  Information  on  posit  Ion- Independent  code)  oT 
cocked  in  such  a  way  that  the  code  can  execute  in  APR  "i 
mapping.  When  the  routines  execute,  the  processor  is  In 
kernel  mode,  and  the  virtual  address  space  Includes  all  of 
the  Executive,  the  pool,  and  the  I/O  page. 

References  within  the  task  image  muf-  be  PC-rolatlve  or  use  a 
special  offset  defined  below.  References  outside  the  task 
Image  must  br  absolute. 

The  following  solutions  are  possible: 

a.  Wrlto  the  TSR,  enable/disable  interrupt  routines,  and 
data  In  posit  ion- Independent  coda. 

b.  Include  the  code  and  data  in  a  common  partition, 
task-build  it  with  absolute  addresses  In  APR  5 
(PAR-ISR:  120000: 20000)  ,  and  link  the  task  to  the  common 
par t  i  t ion . 

c.  Bui'd  the  task  privileged  with  APR  5  mapping  and  use  the 
constant  120000  as  argument  "base"  In  the  CINT$ 
di  rect  ive . 

d.  When  accessing  locations  within  the  task  Image  In 
Immediate  or  absolute  addressing  mode,  use  an  offset  of 


<120000-<base  (,  177700>> 


ISR 


When  the  ISR  Is  entered,  R5  points  to  the  fork  block  in  the 
Interrupt  Transfer  Block  (ITB),  and  R4  is  saved  and  free  to 
be  used.   Registers  RO  through  R3  must  be  saved  and   restored 


If    used.     If   one   ISR   services 
Inter ruptlig  vector  can  be  identified 
which   Is   stored   at  offset  X.vr   In 
example  loads  the  vector  address  Into 

MOV  X. VEC-X.F0RK(R5;  ,R4 


multiple  vectors,  the 
by  the  vector  address, 
the  ITB.  The  following 
R4: 


The  ISR  either  dismisses  the  interrupt  directly  by  an  RTS  PC 
instruction,  or  calls  $F0RK2  if  the  fork  routine  is  to  be 
entered.  When  calling  $F0RK2,  R5  must  point  to  the  fork 
block  in  the  ITB,  and  the  stack  must  be  in  the  same  state  as 
it  was  upon  entry  to  the  ISR.  Note  that  the  call  must  use 
absolute  addressing:   CALL  fl»SF0RK2. 


NOTE 

On  RSX-11-M-PLUS  systems,  do  not  put  the 
ISR  in  a  common.  Commons  can  be 
checkpointed  or  shuffled  independently 
from  the  task  and  the  Executive  only 
disables  checkpointing  and  shuffling  for 
the  task  region. 
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4.  Fork-Level    Routine 

The  fork-level  routine  starts  immediately  after  the  call  to 
$F0RK2.  On  entry,  R4  and  R5  are  the  same  as  when  $P0RK2  was 
called.  All  registers  are  free  to  be  osed .  The  first 
Instruction  of  the  fork  routine  must  be  CLR  eR3,  which 
declares  the  fork  block  free. 

The  fork-level  routine  should  be  entered  if  servicing  the 
Interrupt  takes  more  than  500  microseconds.  It  must  be 
entered  If  an  AST  Is  to  be  queued  or  an  event  flag  Is  to  be 
set.  (Fork  level  Is  discussed  In  greater  detail  In  the 
RSX-llM  Guide  to  Writing  an  I/O  Driver.) 

An  AST  Is  queued  by  calling  the  subroutine  SQASTC. 

Input:   R5   —   pointer  to  fork  block  in  the  ITB 

Output:   if  AST  successfully  queued  --  Carry  bit  ■  0 

If  AST  was  not  specified  by  CINT$  --  Carry  bit  «•  1 

Registers  altered:   RO,  Rl,  R2,  and  R.1 

An  event  flag  Is  set  by  calling  the  subroutine   S3ETF. 

In,ut:  RO   --   event  flag  number 

R5  —  Task  Control  Block  (TCB)  address  of  task  for 
which  flag  Is  to  be  set  --  This  Is  usually, 
but  not  necessarily,  the  task  that  has 
connected  to  the  vector.  This  task's  TCB 
address  i -s  found  at  offset  X.TCB  in  the  ITB. 

Output:   specified  event  flag  set 

Registers  altered:   Rl  and  R2 

Note  that  absolute  addressing  must  be  used  when  callin-^  these 
routines  (and  any  other  Executive  subroutines)  from  fork 
level : 

CALL  a#$QA5TC 

CALL  0#5"ETF 

5.  Enable/Disable  Interrupt  Routine 

The  purpose  of  the  enable/disable  interrupt  routine,  whose 
address  is  included  in  the  directive  call,  is  to  allow  the 
user  to  have  a  routine  automatically  called  in  the  following 
three  cases: 

a.  When  the  directive  is  successfully  executed  to  connect  to 
an  interrupt  vector  'argument  isr  nonzero)  --  The  routine 
is  called  immediately  before  return  to  the  task. 

b.  When  the  directive  i  =?  successfully  executed  to  disconnect 
from  an  interrupt  vector  (argument  isr=0), 

c.  When  the  task  is  a!  orted  or  exits  with  interrupt  vectors 
still  connected. 
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In  case  a,  th«  routine  l«  called  with  the  Carry  bit  cleared; 
In  cases  b  and  c,  wi  h  the  Carry  bi(  set.  In  all  three 
cases,  Rl  Is  a  pointer  to  the  Interrupt  Transfer  Block  TTR'. 
Registers  RO,  R2,  and  RJ  are  free  to  be  used; 
registers  must  be  r«".urned  unmodified.  Retui  .  .i 
accomplished  by  means  of  an   RTS  PC  Instruction. 

Typically,  the  routine  dispatches  to  one  of  two  routine's, 
depending  on  whether  the  Carry  bit  is  cleared  or  set.  One 
routine  sets  Interrupt  eriablj  and  pe;  forms  any  other 
necessary  Initialization;  the  other  clears  Interrupt  enable 
and  cleans  up. 

Note  that  the  ITB  contains  tfie  vector  address,  In  the  event 
that  common  code  Is  used  for  multiple  vectora. 

6.  AST  Routine 

The  fork  routine  may  queue  as  A.ST  for  the  ^;^-;k  rhrough  a  call 
to  the  Executive  routine  SQASTC  as  dc&crl:  When  the 

AST  routine  Is  entered  (at  task  level),  tt..  ;  ,,■  ~.iJ  of  the 
stack  contains  the  vector  address  and  must  be  popped  off  the 
stack  before  AST  exit  (ASTXSS). 

7.  ITB   Structure 

The  following  offsets  are  defined  relative  to  the  start  of 
the  ITB: 

X.  LNK  --  Llr.k  word 

X.JSR  --  Subroutine  call  to  SINTSC 

X.PSW  --  PSW  for  ISR  (low-order  byte) 

X.ISR  --  ISR  address  (relocated) 

X.FORK  --  Start  of  fork  block 

X.REL  --  APR  5  reloCv^tlon  (only  In  mapped  systems) 

X.DSI    --   Address  of  enable/disable  Interrupt  routine 
( relocated) 

X.TCB  --  fCB  address  oc    ownln-]  task 

X.AET  --  Start  of  AST  block 

X.VEC  --  Vector  address 

X.VPC  --  Saved    PC    from    vector 

X.LEN  --  Len:jth    In   bytes   of    ITB 

The  symbols  X. LNK  t^rough  X.TCB  are  defined  locally  by  the 
macro  ITBDFS,  -l.ich  is  Included  In  [  1 ,  1  ]  EXEMC.MI.B .  All 
symbols    aro   defined    globally   by    [  1 ,  1]  EXEMB  .  0L3  . 
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The  Collowing  programming  example  illustrates  the 
directive: 


use   of   the   CINT$ 


.'.  ITLE    PUNTSK    PUNCH   ASCII    TEXT    ON    PAPSR    TAPE    PUNCH 

THIS    TASK    WILL    PUNCH    AN    ASCII    STRING    TO    THE    PAPER    TAPF    PUNCH 
USING    THE    CINTS    DIRECTIVE. 

IT  MUST    BE    RUILT    USING   THE   /PR:0    TASK   BUILDER    SWITCH. 
NOTE    THAT    THIS    METHOD   ALLOWS    A    TASK   TO   BE    A    FULL    32K 
WORDS    LONG.        IP    IT     IS    NECESSARY    TC    ACCESS    THE     I/O    PACE 
IN    OTHER    THAN    THE    ENABLE/DISABLE    ROUTINE    OK    THE    ISR 
THE    TASK    MUST    BE    LINKED   TO    A    COMMON    BLOCK    COVERING 
TH*:    CORh"    T    PART    OF    THE    I/O    PAGE. 


TASK   BUILD   COMMAND    FILEi 

P'JNTSK/MM/PR!0/-FP,PUNTSK/-SP/MA-PUNTSK 
ri,541hSXllM.STB/SS 
/ 

GBLDEr^SVECTR:74 
GBLDEF-SDVCSR: 177554 
UNITS-1 
ASG-TI : 1 
PAR»GEN: 0; 40000 


JT    IS    POSSIBLE    TO    HAVE    THIS    TASK    TyPE    ON    THK    CONSOLE    TERMINAL 
IF    THERE    IS    NO    PAPER    TAPE    PUNCH    AVAILABLE.       TO    DO    TH"3    THE 
VECTOR    FOR    THE    CONSOLE    OUTPUT    MUST   APPEAR    TO    BE    UNUSED.       THIS 
MAY    BE    DONE    BY     (ON    A    TERMINAL    OTHER    THAN    THE    CONSOLE  1 )     OPENING 
THE    VECTOR    LOCATION     (64;     AND    REPLACING    ITS    CONTENTS    WTTH 
THE    VALUE    OF     'SNEO'    AS    OBTAINED    FROM    A    MAP    OT    THE    SYSTEM.     BE 
SURE    TO    REMEMBER    THE    OLD    VALUE    OR    YOUR    CONSOLE    WILL    BE    DEAD 
UNTIL    YOU    REBOOT    THE    SYSTEM.       NOW    TASK    BUILD    USING    THE    FOLLOWING 
COMMAND    FILE: 

PUNTTY/MM/PR:0,/-FP,PUNTTY/-SP/MA-PUNTSK 

(l,54)RSXnM.STB/SS 

/ 

GBLDEF-SVECTR:64 

GBLDFF»SDVf"=R;  1775ti4 

UNITS=1 

ASG-TI:  1 

PAROGEN: 0: 40000 


NOTE    THAT    IN    THE    ABOVE    TWO    TKB    COMMAND    FILES    THE    FOLLOWING 
CHANGES    MUST   BE   MADE     IN    ORDER    TO    RUN    ON    AN    UNMAPPED    SYSTEM: 

1)  /MM    SHOULD    BE    CHANGED   TO    /-MM 

2)  'PAR»GEN:0: 40000'     SHOULD    BT    CHANGED   TO 
•PAR»GEN:40000: 40000' 

IN    ADDITION,     PLACE    A    SEMI -COLON    IN    FRONT    OF    THE    SOURCE    LINE 
;  BELOW    THAT    DEFINE    THE    SYMBOL     'MSSMGE'. 

!mCALL    CINTS,     QIOW$,     CLEFSS,     WTSESS,     EXITSS,     DIR5 

;     LOCAL    SYMBOLS 


• 


• 


• 
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I.UN .  TT 
EFN.TT 
EFN.Wr 
M$$MCB 


;LUN    FOR    TERMINAI.    I/O 

iirn  roR  terminal  i/o 

;EFN  TO  WAIT  FOR  PUN.'HING  TO  COMPLETE 
;Di;FINE  This  SYMBOL  TO  RUN  ON  MAPPED  SYSTEM 


AND  A  OIO  TO  OUTP'IT 


MArRO  TC  1KNCRATK  AN  ASCII  STRIN<; 
THE  STRING  TO  THE  TERMINAL. 

MRSSC    NAM, STRING 

WHERE 


XAM       I'l  THE  NAME  OF  THE  GENERATED  QIC)    DPB 
STRING   IS  THE  ASCII  STRING  TO  uUTPUT 


LBLt 
NAM: 


CINTi 


.MACRO      MKSSG         NAM , STR INC, ?LBL 

SCHR-0 

.IRPC         X,<STHING> 

SCHR-SCHR+1 

ENDR 

.ENABL       LSB 

.ASCII       /STRING/ 

.EVEN 

OIOWS       tO.WVB,LUN.TT,EFN.TT,,,,<LBL,$CHR,40> 

.DSABL       LSB 

.ENDM 


HESSG 
MESSU 


HELLO, CCONNECT    TO     INTERRUPT    TEST) 
Cr'VRK,<CONNECT    TO    INTERRUPT    WORK;: 


-CHECK    THE    PAPER    TA    E    PUNCH> 


CINTS       SVECTR, S8ASE, $PNI3R, SPNEDI , PR  4 


DISCON:CINT$       SVECTR, 0,C 


+  f 


;?ONNECT    TO    INTERRUPT 

;  VECTOR»SVECTR 

;  BASE. FOR. MAPPING-SBASE 

;  ISR'SPNISR 

;  ENB. DSABL. H.'N-$PNEDI 

I  PRI0-PR4 

'DISCONNECT    FROM     INTERRUPT 
VECTOR'7  4 


ENTRY    POINT   T'^    THE    PJflCH    TASK.       THE    TASK   WILL    A  JNOUNCE 
ITSELF    ON    THE    INITIATING    TERMINAL,    CONNECT   TO    THE 
SPECIFIED    VECTOR,     OUTPUT    THE    ASCII    STRING,    AND    THEN 
OUTPUT    A    MESSAGE    THAT    IT    WAS    SUCCESSFUL.        IF    THE    TASK 
TERMINATES    WITH    AN    I/O    TRAP    THP:    CONNECT-TO-INTERHUPT 
DIRECTIVE    FAILED,    AND    ,<  1    WILL    CONTAIN    THE    DSW    RETURNED 
IN    ORDER    TO    DIAGN05E    THE    ERRO.!. 


SPUNTK: :DIRS 

IHELLO 

DIRS 

tCINT 

BCS 

ERRl 

WTSESS 

lEtN.WF 

DIRS 

iDISCON 

DIRS 

ICINWRK 

EXITSS 

ANNOUNCE    THAT   WE    ARE    HERE 

CONNECT    TO   THE    PUNCH 

THIS    CAN    BE    EITHER    THE    TERMINAL 
OR    THE    PAPER    TAPE    PUNv-R. 

IF    CS    THEN    DIRECTIVE    ERROR 

WAIT    FOR    PUNCH    TO    FINISH 

DISCONNECT    PROM     INTERRUPTS 

TELL    USER    THAT    CINT   WORKS 
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BRPl:         MOV  ll.RO  i ERROR    I    1 

MOV  SDSW.Rl  (GET   THE    DSW   TO   SHOW   THK   CINT    ERROR    RETURN 

lOT  (DUMP   REGISTERS 

SBAHE)  ;THIS    IS    THE    BASE    OF    THE    MAPPING    USED 

(BY    THE    EXECUTIVE    WHEN    MAPPING    TO    THE 
('DRIVER'.    THIS    MAPPING    IS    REQUIRED 
;ONLY    ON    MAPPED    SYSTEMS (    UNMAPPED 
(SYSTEMS    DO   NOT    HAVE   THIS    PROBLEM. 


I 
»  — 


FOLLOWING    IS    THE   ASCII    STRING    PUNCHED   BY  THIS    TASK. 


PUNMSG: 


.NLIST 

.ASCtZ 

.LIST 

.  EVEN 


BEX 

/ABCDEfGHI.JKLMNOPORSTUVWXYZOl214S67«9l(»|S%" 

BEX 


4*()    +--/<15><12> 


PUNPTR:        .WORD         0 

TSKTCB:        .WORD         0 

PUNCSR:       .WORD         $DVCSR 

PUNBUF:       .WORD         SDVCSR+2 

•  +  + 

i  ENABLE/Dir"ABLE  ROUTINE. 


(POINTER  INTO  PUNMSG  FOR  ISR 
(TCB  ADDRESS  OF  TASK 
(PAPER  TAPE  PUNCH   "R  ADDRESS 
(PAPER  TAPE  PUNCH  BUFFER  ADDRESS 


THIS  ROUTINE  IS  CALLED  BY  THE  EXEC  ON  EITHER  A  CONNECT  OR  DISCONNECT 
FROM  INTERRUPT  VECTOR  REQUEST,  OR  WHEN  THE  TASK  EXITS  WITH  INTERRUPT 
VECTORS  STILL  CONNECTED. 


• 


ENTRY   CONDITIONS: 


C-CLEAR 
C-SET 

STKTCB 

ACTION: 


THIS    IS    A   SUCCESSFUL   CONNECT. 
THIS    IS    A    DISCONNECT. 

THE    TCB    ADDRESS    OF    THE    CURRENTLY    EXECUTING    TASK     (MEM! 


I?    THE    C-BIT    IS    SET   WE   MERELY    DISABLE    THE    PUNCH    AND    RETURN.        IF 
(  THE   C-BIT    IS    CLEAR    WE   WILL    ENABLE    THE    PUNCH    TO    INTERRUPT.       THIS 

;  WILL    IMMEDIATELY    CAUSE    AN    INTERRUPT    AND   THE    INTERRUPT    SERVICE 

!  ROUTINE    WILL    OUTPUT    CHARACTERS    TO    THE    PUNCH    (ONE    PER 

(  INTERRUPT)    UNTIL    A    ZERO    BYTE    IS    OUTPUT.       THE    ISR    WILL    THEN    KOHK 

AND    SET    THE    LOCAL    EVENT    FLAG    'EFN.WF'.    THIS    WILL    THEN    CAUSE    THE 

TASK    PORTION    OF    THIS    TASK    TO    CONTINUE    EXECUTING    AND    EVENTUALLY 

EXIT. 
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tPNEDIilBCS  ?0S  ;tF    CS    THEN    DISCONNECT 

MOV  ?»$TKTCB,TSKTOB     ,COPY    TASK    TCH    AllDREHSi    FOR    LATER 

;H0    WE    CAN    i'.ET    EPN. 

.ir    DF    MSSMOE  /MAPPED   SYSTEM/ 

MOV  IPUNMSG*120000-<SBASE4l77700>,PUNPTH    /RELOCATE    ADDRESS 

(TO    APR    •)  MAPPINO,    AND   SET    UP 
/BUrFKR    POINTER 

.IFF  MSSMOE  /UNMAPPED   SYSTEM? 

MOV  JPUNMSG.PUNPTR     /SET    UP    BUFFER    POINTER 

•  ENDO 

BIS       I100,»PUNCSH  /ALLOW  INTERRUPTS 
RETURN 

/WHEN  WE  ARE  DONE  PUNCHING 

20S:     BIC       llOO.iPUNCSR  /DISABLE  INTERRUPTS 
RETURN 

.END 
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CLEFS 

5.3.7     Clear    Event    Flag 

The    Clear    Event    Flag    directive      Instructs      the      aystpm      to      report      an 
Indicated    wvent    flaq's    polarity   and    thet\    clear    it. 

FORTRAN   Call . 

CALL   CLREF    (efn(,lds] ) 

efn   =   Event  flag  number 

ids   »   Directive  status 

Macro  Cdl 1 : 

CLEFS    efn 

efn   =   Event  flag  number 

Macro  Expansion: 

CLEFS    52. 

.BYTE         31., 2  ;CLEF$    MACRO    UIC,    DPB    SIZE=2    WORDS 

.WORD         52.  ;EVENT    FLA^    NUMBER    52. 

Lcijal    Symbol    Definitions: 

C.LEEF      --      Event    flag    number     (2) 
DSW   Return    Codes: 

IS.CLR      --      Successful    completion;      flag    was   already  clear. 

IS. SET      —      Successful    completion;       flag    va;    set. 

lE.IEF  —  Invalid  event  flag  number  (EFN<'1,  or  EFN>96,  if  group 
global  event  flags  exist  for  the  task's  group;  or 
EFN>f>4    i  f    not)  . 

TE.ADP      --      Part      or"    the    DPB    Is   out   of    the    tsRMing    t.isk's    address 

space.  ^^ 

lE.SDP      --      Die    or    DPii   size    is    invalid.  ^^ 
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CMKTS 

5.3.8  Cancel  Mark  Time  Kequnsts 

The  Cancel  Mark  Time  Ho.iuesrs  directive  Instructs  the  system  to  cancel 
!  ^^^^'^  !"  '^^'■\''''"'e  Request  or  all  Mark  Time  requests  that  have  heen 
made  by  the  Issuing  task. 

FORTRAN  Cal 1 : 

CALL  CANMT  (fefn)  t,:d8! ) 

efn   ="   Event  flag  number 

ids   =   Directive  status 

Macro  Ca 11  : 

CMKTS   [efn,ast,err) 

err   =»   trror  routine  adaress 

efn   ="   Event  flag  number 

ast   =   Mark  time  AST  address 

Macro  Expansion: 

CMKTS  52. ,«RKAST,ERR  ;NOTE:  THERE  ^RE  TWO  IGNORED  ARGUMENTS 

.BYTE  27., 3  ;CMKT$  MACRO  DIC,  DPB  SrZE=3  WORDS 

.WORD  52.  ;EVENT  FLAG  NUMBER  52. 

.WOkJ  MRKAST  .-address  of  MARK  TIME  REQUEST  AST  ROUTIKE 

NOTE 

The  above  example  will  cancel  only  the 
Mark  Time  requests  that  were  specified 
with  efn  52  or  the  AST  address  MRKAST. 
If  "o  3st  or  efn  parameters  are 
specified,  all  Mark  Time  requests  issued 
by  the  task  are  cancelled,  and  the  DPH 
size  will  equal  1. 

Local  Symbol  Definitions: 

C.MKEF   --   Event  flag  number  (2, 

C.MKAE   --   Mark  Time  Request  AST  routine  address  (2) 
DSW  Return  Codes: 

IS. sue   —   Successful  completion. 

lE.ADP   —   Part  of  the   DPB  is  out  of  the  issuing  t,-.sk's  address 
space . 

lE.SDP   --   Die  or  DPB  size  is  invalid. 
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No  t  e  5  : 


1.  tf  neither  the  efn  nor  ast  parameters  are  speclfl«d,  all  Mark 
Time  Requests  Issued  by  th«  tank  .ire  canceled.  In  addition, 
thj  DPB  s  i  zfc  will  i)e  one  word.  (When  eltf.er  the  efn  and/or 
ust  parameters  are  specified,  the  DHB  size  will  be  three 
words. ) 

2.  If  both  efn  and  ast  parameters  are  specified  (and  nonzero), 
only  Mark  Time  Requests  i  '  '  ^ he  task  specifying  either 
that  event  f  1  aq  or  AST  add;         anceleil. 

3.  If  only  ont?  efn  or  ast  parameter  Is  specified  {an'.l  nonzero), 
only  Mark  Tim.-'  Requests  Issued  by  tt.e  task  speclfylnq  the 
event  flaq  or  A.ST  address  are  canceled. 

4.  If  the  specified  event  flaq  Is  a  qroup  qlobal,  then  the  use 
count  for  the  event  f I aq ' s  qroup  Is  i un  down  when  a  Mark  Time 
request  is  canceled. 


o 
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5.3.9   Connect 

The  Connect  directive  synchronizes  the  task  issuing  the  directive  with 
the  exit  or  emit  status  of  another  task  (offspring)  that  is  already 
active.  Execution  of  this  ri-rective  queues  an  Offspring  Control  Block 
(OCB)  to  the  offspring  task,  and  increments  the  issuin'j  task's  rundown 
count  (contained  in  the  issuing  task's  Task  Control  Block).  The 
rundown  count  is  maintained  to  indicate  the  combined  total  number  of 
tasks  presently  connected  as  offspring  tasks  and  the  total  number  of 
virtual  terminals  the  task  has  created.  The  exit  AST  routine  is 
called  when  the  offspring  exits  or  emits  status  with  the  address  of 
the  associated  e.:it  status  block  on  the  stack.  This  directive  should 
not  be  issued  to  connect  to  Command  Line  Interpreter  (CLI)  tasks;  it 
is  illegal  to  connect  to  a  CLI  task. 

FORTRAN  Call : 

CALL  CNCT  ;rt name,  [ iefn]  , [last]  , [ iesb]  , [ iparm]  [ , ids) ) 

rtname  =  A  s  ingle-preciF.ion,  floating-point  variable 
containing  the  offspring  task  name  in  Radix-50 
format . 

iefn  =  Event  flag  to  be  set  when  the  offspring  task  exits 
or  emits  status 

last  =  Name  of  in  AST  routine  to  be  called  when  the 
offspring  task  exits  or  emits  status 

iesb  =  Name  of  an  8-word  status  block  to  be  written  when 
the  offspring  task  exits  or  emits  status 

Word    0  —  Offspring  task  exit  status 

Word    1  —  TKTN  abort  code 

Word  2-7  --  Reserved 

NOTE 

The  exit  status  block  defaults  to  one  word. 
To  use  the  8-word  exit  status  block,  you 
must  specify  the  logical  or  of  the  symbol 
SP.WX8  and  the  event  flag  number  in  the  iefn 
parameter  above. 


iparm    =  Na ne  of  a  word  to  receive  the  status   block   address 
v.'.ien  an  AST  occurs 

ids     =   Integer  to  receive  the  Directive  Status  Word 

Macro  Cal  1  : 

CNCTS    tname,  [efn] , [east] , [esb] 

tname    =   Name  C^ADSO)  of  the  offspring  task  to  be  connected 

efn      =   The  event  flag  to  be  cleared   on   issuance   and   set 
when  tho  offspring  tasK  exits  or  omits  status 
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Address  of   an  AST  routine   to   be   called   when   the 
offspring  task  exits  or  emits  status 

Address  of  an  8-word  status  block  to  be  written  when 
the  offspring  task  exits  or  emit  status 

word    0  --  Offspring  task  exit  status 

word    1  —  TKTN  abort  code 

word  2-7  —  Reserved 


NOTE 

The  exit  status  block  defaults  to  one  word. 
To  use  the  S-word  exit  status  block,  you 
must  specify  the  logical  or  of  the  symbol 
SP.WX8  and  the  event  flag  number  in  the  efn 
parameter   above. 


Macro    Expansion: 


CNCT$ 

ALPHA, 

•  BYTE 

143.  ,6 

.RAD50 

ALPHA 

.BYTE 

1 

.BYTE 

16. 

.WORD 

CONAST 

.WORD 

STBUF 

CNCT$    MACRO    DIC,     DPB    SI2E=6    WORDS 

OFFSPRING    TASK    NAME 

EVENT    FLAG    NO    =    1 

EXIT    STATUS    BLOCK    CONSTANT 

AST  ROUTINE  ADDRESS 

EXIT    STATOS    BLOCK    ADDRESS 

Local    Symbol  Definitions: 

C.NCTN  --      Task    name    (4) 

C.NCEF  --   Event  flag  (2) 

C.NCEA  --  AST  routine  address  (2) 

C.NCES  —   Exit  status  block  address  (2) 
DSW  Return  Codes: 

IS. sue  --   Successful  completion. 

lE.UPN   —   Insufficient  dynamic  memory  to  allocate  an  offspring 
control  block. 

IE.  INS   --   The  specified  task  was  a  command  line  interpreter. 

IE. ACT   --   The  specified  task  was  not  active. 

lE.IEF  —  Invalid  event  flag  number  (EFN<0,  or  EFN>96  if  group 
global  event  flags  exist  for  the  task's  group;  or 
EFN>64  i  f  not)  . 

lE.ADP   —   Part   of  the  DPB  or  exit   status  block  is  not  in  the 
issuing  task's  address  space. 

lE.SDP   —   DIC  or  DPB  size  is  invalid. 
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Notes; 


1,  If  the  specified  event  flag  is  a  group  global,  the  use  count 
for  the  event  flag's  group  is  Incremented  to  prevent 
premature  elimination  of  the  event  flags.  The  use  count  is 
run  down  when: 

•  The  connected  task  returns  status 

•  The  issuing  task  exits  before  status  is  returned 

2.  Do  not  chango  the  virtual  mapping  of  the  exit  status  block 
while  the  connection  is  in  effect.  Doing  so  may  cause 
obscure  errors  since  the  exit  status  block  is  always  returned 
to  the  virtual  address  specified  regardless  of  the  physical 
address  to  whirh  it  is  mapped. 
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S.3.10  Checicpoint  Common  Region 

This  dii  ctive  instructs  the  system  to  force  the  specified  Read/Write 
common  region  to  be  checkpo inted .  This  directive  stops  all  the  tasks 
that  ai.i  mapped  to  the  common  region,  writes  the  common  region  out  ..o 
the  disk  and  then  unstops  che  tasks. 

The  issuing  task  must  be  privileged  (PR:0). 

The  issuing  task  must  be  attached  to  the  specified  common  region. 

If  the  issuing  task  is  mapped  to  the  specified  common  region,  it  is 
blocked.  Any  task  (including  the  issuing  task)  Is  also  blocked  If  it 
maps  to  the  common  region  while  the  checkpoint  Is  in  progress.  If  the 
task  was  built  with  the  /COMMON=  qualifier,  the  task  will  be  blocked 
when  it  issues  this  directive.  If  the  task  becomes  attached  by  means 
of  the  Attach  Region  directive,  it  is  not  blocked  unless  it  issues  a 
Map  directive. 

You  can  use  this  directive   to   preserve   changes   made   to   a  memory 

resident   common   region.   When  a  region  is  checkpo inted ,  it  is  copied 

to  its  own   image   on   the  disk   and   not   to   the   checkpoint  file. 

Therefore,  any  update  to  the  memory  resident  copy  of  the  common  region 
becomes  permanent. 

FORTRAN  Call  : 

CALL  CPCR (name (, ids] ) 

name  =  Name   (in   RAD50)   of   the   common    region    to    be 
checkpointed 

ids   =  Directive  Status 

Macro  Call : 

CPCR$    name 

name  =  Name  of  the  common  region  to  be  checkpointed 

Macro  Expansion: 

CPCRS   NAME 

.BYTE         205., 3  ;DIC    =205.,    DPB    SIZE=    ^    WORDS 

.RAD50      /NAME/ 

Local    Symbol    Definitions: 

CPCR        —     Name   of   common    region 
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DSW   Return   Codes: 

IE. sue      —     Successful    completion. 

lE.PRI      —     Privilege  violation. 

lE.NSP     —     The   specified   common    region  does   not   exist. 

IE. ITS      --      I/O   in    progress   to    the   specified    region. 

lE.ADP      —      Part   of    the    DPB    Is   out   of    the    issuing    task's      address 
space. 

IB.SDP      —      Die  or    DPB   size    is    invalid. 
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5.3.11   Create  Address  Window 

The  Create  Address  Window  directive  creates  a  new  virtual  address 
window  by  allocating  a  window  block  from  the  header  of  the  issuing 
task  and  establishing  ics  virtual  address  base  and  size.  (Space  tor 
the  window  block  has  to  be  reserved  at  task-build  time  by  means  of  the 
WNDWS  keyword.  See  the  RSX-1 1  M/M-PL'JS  Task  Builder  Manual .)  Execution 
of  this  directive  unmaps  and  then  eliminates  any  exisTTng  windows  that 
overlap  the  specified  range  of  virtual  addresses.  If  the  window  is 
successfully  created,  the  Executive  returns  an  8-bit  window  ID  to  the 
task . 

The  8-bit  window  ID  returned  to  the  task  is  a  number  from  1  to  15  (1 
to  23  on  RSX-llM-PL'JS  systems),  which  is  an  index  to  the  window  block 
in  the  task's  header.  The  window  block  describes  the  created  address 
window. 

It  WS.SIS  in  the  window  status  word  is  set,  the  Executive  creates  the 
window  in  supervisor-mode  I-space.  Program  control  can  subsequently 
be  transferred  to  supervisor-mode  I-space  upon  issuing  a  Supervisor 
Call  directive. 

If  WS.UDS  in  the  window  status  word  Is  set,  the  Executive  creates  the 
window  in  user-mode  D-space. 

If  WS.MAP  in  the  window  status  word  is  set,  the  Executive  proceeds  to 
map  the  window  according  to  the  Window  Deiinltion  Block  input 
parameters. 

A  task  can  specify  any  length  for  che  mapping  3sslgni..ent  that  is  less 
than  or  equal  to  both  the  window  size  specified  when  the  window  \^as 
created,  and  the  length  remaining  between  the  specified  offset  within 
thp  region  and  the  end  of  the  region. 

If  W.NLEN  is  set  co  0,  the  leigth  defaults  to  either  the  window  size 
or  the  length  remaining  in  the  region,  whichever  is  smaller.  (Because 
the  Executive  returns  the  actual  len^jth  mapped  as  an  output  parameter, 
the  task  must  clear  that  offset  before  issuing  the  directive  each  time 
It  wants  *-.o  default  the  length  of  the  map.) 

The  values  that  can  be  assigned  to  W.NOFF  depend  on  the  setting  of  bit 
WS.64B  in  the  window  status  word  (W.MSTS;; 

•  If  WS.64B  =  0,  the  offset  specified  in  W.NOFF  must  represent  a 
multiple  of  256  words  (512  bytes).  Because  the  value  of 
W.NOFF  is  expr«*':sed  in  units  of  32-word  bloct>.s,  the  value  must 
be  a  mul  t  i  pie  of  8  . 

•  If  WS,64B  =  1,  the  task  can  align  on  32-word  boundaries;  the 
programmer  can  therefore  specify  any  offset  within  the  region. 


5-36 


DIRKCTIVK  DESCRIPTIONS 

NOTE 

Applications  dependent  on  32-word  or 
64-bytt'  alignment  (WS.64B  =  1)  may  not 
be  compatible  with  future  RSX  emulators. 
To  avoid  future  Incompatibility, 
programmers  should  write  applications 
adaptable  to  either  alignment 
requirement.  The  bit  sotting  of  WS.64B 
could  be  a  parameter  chosen  at  assembly 
time  (by  means  of  a  prefix  file),  it 
task-build  time  (as  input  to  the  GBLDEF 
option),  or  at  run  time  (by  means  of 
command  input ) . 

k-'ORTRAN  Call  : 

CALL    CRAW     ( iwdb[ .ids) ) 

iwdb      =      An    8-word    integer    array  containing    a   window  definition 
block    (see    Section    3.5.2.2) 

Ids        =      Dl^ec^lve   status 
Macro   Cal 1  : 

CRAWS        wdb 

wdb   =  Window  Definition  Block  address 

Macro  Expansion: 

CRAWS    WDBADR 

.BYTE    117., 2    ;CRAW$  MACRO  DIC,  DPB  SIi:e  =  2  WORDS 

.WORD    WDBADR    ;WDB  ADDRESS 

Window  Definition  Block  Parameters: 

Input  parameters: 

Array       OfCset 
Element 

Iwdb(l),  W.NAPR      --      Base      APR      of    the    address      window      to      ,be 

bits    8-15  created. 

iwdb(3)  W.NSIZ      --      Desired      size,    in    32-word    blocks,    of      the 

address   window. 

iwdb(4)  W.NRID      —      ID   of    the    region    to    which      the    new   window 

is    to    be   mapped,    or    0    for    task    region    (t 
be    specified    only    if   WS.MAP'l). 

iwdb(5)  W.NOFF      --      Offset    in      32-word    blocks      from    the    stacf 

of  the  region  at  which  the  window  Is  to 
start  mapping  (to  be  specified  only  If 
WS.MAP=1).  Note  that  if  WS.64B  in  the 
window  status  word  equals  0,  the  value 
specified    must    be   a   multiple   of   8. 
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iwdb(6)  W.NLEN      —      Length    in    32-word    blocks    to    be   mapped,    or 

0  if  the  length  is  to  default  to  either 
the  size  of  the  window  or  the  space 
remaining  in  the  region,  whichever  is 
smaller  {to  be  specified  only  if 
WS.MAP-=1)  . 

iwd>j(7)  W.NSTS      —      Bit    settings^-    in    the    window      status    word: 

Definition 

1  if  the  new  window  is  to  be 
mapped 

1  if  the  mapping  assignment 
is  to  occur  with  write  access 

0  for  256-word  {512-byte) 
alignment;  or  1  for  32-word 
(64-byte)  alignment 

Output  parameters 

iwdh(l),     W.NID    —   ID  assigned  to  the  window 
bits  0-7 

iwdb(2)      W.NBA3   —   Virtual  address  base  of  the  now  window 

i,vub(6)      W.NLEN   —   Length,   in   32-word    blocks,    actually 

mapped  by  the  window 

iwdb(7)      V\.N3TS   —   Bit  settings^  in  the  window   status  word: 

Bit         Definition  (if  bit=l) 

WS.CRW  Address    window   was 

successfully  created. 

WS.UNM       At  least  one  window  was 
unmapped . 

WS.ELW       At  least  one  window  was 
el  iminc. ced . 

WS.RRF       Reference  was  successfully 
received . 

WS.NBP      Do  not  bypass  the  cache  (for 
multiprocessor  systems). 

WS.RES       Map  only  if  resident. 

WS.NAT      Create  attachment  descriptor 
only  if  necessary  (for  Send 
By  Reference  directives). 


1.  If  you   are   a   FORTRAN   proqramm'^r,   refer   to   Section   5.5.  2   to 
determine  the  bit  values  representeu  by  the  symbolic  names  describci. 
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Bit         Definition  (if  bit-1) 

WS.64B       Define  the  task's  permitted 
alignment  boundaries   --   0 
for  ?56-word  (512-byte) 
alignment;   or  1  for  32-word 
(64-byte)  alignment. 

WS.MAP      Window  is  to  be  mapped. 

WS.RCX      Exit  if  no  references  to 
receive . 

WS.SIS      Create  window  in  supervisor 
I-space. 

WS.UDS      Great'.*  window  in  user 
D-space. 

WS.DEL      Send  with  delete  access. 

WS.EXT       Send  with  extend  access. 

WS.WRT       Send  with  write  access  or  map 
with  write  access. 

WS.RED      Send  with  read  access. 

Local  Symbol  Definitions: 

C.RABA   —  Window  definition  block  address  (2) 
DSW  Return  Codes: 

IS. sue   —   Successful  completion. 

lE.HWR   —   Directive  failed  in  mapping   storage   because   region 
has  incurred  a  parity  error. 

lE.PRI   --  Requested  access  denied  at  mapping  stage. 

lE.NVR   —   Invalid  region  ID. 

lE.ALG   —  Task  specified  either  an  invalid  base   APR  and  window 

si7.e  combination,  or  an  invalid   region   offset   and 

length   combination   in  the   mapping  assignment;   or 

WS.64B  =  0  and  the  value  of  W.NOFF  is  not  a   multiple 
of  8. 

lE.'.'OV   —  No  window   blocks   available  in   task's  header. 

lE.ADP   —   Part  of  the  DPB   or  WDB   is  out  of  the  issuing  task's 
address  space. 


lE.SDP   -- 


DIG  or  DPB  size  is  invalid, 
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5.3.12   Create  Group  Global  Event  Flags 

The  Create  Group  Global  Event  Flags  directive  creates  a  Group  Global 
Event  Flag  Control  Block  (GFB)  and  links  it  into  the  GFB  list.  If  a 
GFB  for  the  specified  group  is  not  present  when  the  directive  Is 
issued,  the  Executive  creates  the  GFB  data  structure  with  all  event 
flags  initialized  to  zero.  If  a  GFB  is  present  when  the  directive  Is 
issued,  the  Executive  uses  the  present  GFB  and  the  event  flags  are  not 
iniLialized.  However,  if  the  GFB  is  marked  for  delete  (by  a 
previously  issued  Eliminate  Group  Global  Event  Flags  directive),  the 
Executive  clears  the  GS.DEL  bit  (see  Section  5.3.20). 

If  the  specified  group  code  matches  the  group  code  of  the  issuing 
task's  protection  UIC  (H.CUIC+1),  this  directive  increments  the  access 
count  for  the  event  flags.  This  locks  the  event  flags  so  they  cannot 
be  eliminated  by  another  task  that  is  sharing  them.  The  Issuing  task 
can  explicitly  unlock  the  event  flags  with  an  Unlock  Group  Global 
Event  Flags  directive  or  an  Eliminate  Group  Global  Event  Flag's 
directive.  The  Executive  automatically  unlocks  the  event  flags  when 
the  task  exits  if  necessary.  Note  that  a  task  may  not  lock  the  event 
flags  .;iore  than  once  in  succession.  Any  attempt  to  lock  event  flags 
that  are  already  locked  will  return  the  lE.RSU  error  code. 

FORTRAN  Call : 

CALL  CRGF  ( [group] [, ids] ) 

group  =  Group  number  for  the  flags  to  be  created.  Only 
privileged  tasks  can  specify  group  numbers  other  than 
the  issuing  task's  group  UIC.  If  not  specified,  the 
task's  protection  UIC  (H.CUIC+1)  in  the  task's  header 
is  used. 

ids    =   Integer  to  receive  the  Directive  Status  Word. 

Macro  Cal 1 : 

CRGFS  [group] 

group  -  Group  number  for  the  flags  to  be  created.  Only 
privileged  tasks  can  specify  group  numbers  other  than 
the  issuing  task's  group  UIC.  If  not  specified,  the 
task's  protection  UIC  (H.CUIC+1)  in  the  task's  header 
is   used. 

Macro    Expansion: 

CRGFS  4 

.BYTE  157.,  2  ;CRGF$    MACRO    DIC,    DPB    SIZE  =  2    WORD'J 

.WORD  4  ;GROUP    4   GLOBAL    EVENT    FLAGS 

Local    Symbol    Definitions: 

C.RGRP    —  Group    Number    (2) 
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DSW   Return    Codes: 

IS. sue    —   Successful    completion. 

lE.UPN    —    Insufficient   dynamic    storage. 

lE.PRI    —   Privilege   violation. 

IE.  lUI    --    Invalid    group.  •' 

lE.RSU    —   Event    flags   already   exist   or    are    already    locked. 

lE.APD   —   Part   of    the    DPB    is   out   of    the      i'isuing      task's      address 
space. 


IE. Die    —   DIG   or    DPB    size    is    invalid 


Note; 


A  privileged  task  may  specify  group  numbers  other  than  the  group 
UIC  of  the  issuing  task.  However,  the  task  can  only  lock  the 
event  flags  created  for  its  own  group.  This  directive  does  not 
return  an  error  if  it  does  not  lock  the  event  flags. 
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5.3.13   Create  Region 

The  Create  Region  directive  creates  a  dynamic  region  in  a 
system-controlled  partition  and  optionally  attaches  it  to  the  issuing 
task . 

If  RS.ATT  is  set  in  the  region  status  word,  the  Executive  attempts  to 

attach   the   task   to  the  newly  created  region.   If  no  region  name  has 

been  specified,  the  user's  program  must  set  RS.ATT  (see  the 
description  of  the  Attach  Region  directive). 

By  default,  the  Executive  automatically  marks  a  dynamically  created 
region  for  deletion  when  the  last  task  detaches  from  it.  To  overriiie 
this  default  condition,  set  RS.NDL  in  the  region  status  word  as  an 
input  parameter.  Be  careful  in  considering  to  override  the 
delete-on-last-detach  option.  An  error  within  a  program  c^u  cause  the 
system  to  lock  by  leaving  no  free  space  in  a  system-controlled 
part i  tion . 

If  the  region  is  not  given  a  name,  the  Executive  itjnores  the  state  of 
RS.NDL.  All  unnamed  regions  are  deleted  when  the  last  task  detaches 
from  them. 

Named  regions  in  RSX-1 IM-PLUS  systems  are  put  in  the  Common  Block 
Directory  (CBD) .  However,  memory  is  not  allocated  until  the  Executive 
maps  a  task  to  the  region. 

The  Executive  returns  an  error  if  there  is  not  enough  space  to 
accommodate  the  region  in  the  specified  partition.   See  Notes  below. 

FORTRAN  Call : 

CALL  CRRG  {irdb[  ,idsl ) 

irdb   =   An  8-word  integer  array  containing  a  Region  Detinition 
Block  (see  Section  3.5.1.2) 

ids    =   Directive  status 
Macro  Cal 1 : 

CRRGS    rdb 

rdb   =   Region  Definition  Block  address 

Macro  Expansion: 

CRRGS    RDBADR 

.BYTE    55.,  2        ;CRRG$  MACRO  DrC,  DPB  SI?.E  =  2  WORDS 

.WORD    RDBADR        ;RDB  ADDRESS 

Region  Definition  Block  Parameters: 

Input  parameters: 

Array       Offset 
Element 

irdb(2)  R.GSIZ      —      Size,       in      32-word    blocks,    of    the      region 

to    be    created 
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irdb(3)(4)       R.GNAM      --      Name   of        the    region      to    be  created,    or    0 

for    no    name 

irdb(5)  (6)   R.GPAR   --   Name  of  the   system-controlled   partition 

in  which  the  region  Is  to  be  allocated, 
or  0  for  the  partition  in  which  the  task 
is  running 

lrdb{7)      R.GSTS   --   Bit  settings^   in  the  region  status  word: 

Bit         Definition  (if  bit^l) 

RS.CRR      Region  was  successfully 
created . 

RS.UNM      At  least  one  window  was 
unmapped  on  a  detach. 

RS.MDL      Mark  region  for  deletion  on 
last  detach. 

RS.NDL       The  region  should  not  be 
deleted  on  last  detach. 

RS.ATT      Created  region  should  be 
attached . 

R5.NEX      Created  region  is  not 
extend  i  ble . 

RS.RED      Read  access  is  desired  on 
attach . 

RS.WRT      Write  access  is  desired  on 
attach. 

RS.EXT      Extend  access  is  desired  on 
attach. 

RS.DEL      Delete  access  is  desired  on 
attach. 

irdb(8)      R.GPRO   --   Protection    word     for     the     region 

(DEWR, DEWR, DEWR, DEWR) 

Output  parameters 

irdb(i)      R.GID    —   ID   assigned    to   the    created   region 

(returned  if  RS.ATT=1) 

irdb(2)  R.GSIZ      --      Size      in    32-word      blocks   of      th^    attached 

region    (returned    if    RS.ATT=l) 

irdb(7)  R.GSTS      —      Bit    settings^    in    the    rogion    status      word: 

Bit  Definition 

RS.CRR       1  if  'uhe  region  was 
successfully  created 


1.  If  you  are  a  FORTRAN  programmer,  refer  to  Section  l.S.l   ^o   define 
the  bit  values  represented  by  the  symbolic  names  described. 
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Local    Symbol    Def  ini  ^  i  oris  : 

r.RRBA      —      Region   Definition   Block   address    (2) 
DSW    Return    Codes: 

IS. sue      —      Successful    completion. 


lE.UPN 


lE.HWR 


IE. PR  I 


lE.PNS 


ie:.adp 


A  Partition  Control  Block  (PCB)  or  an  attachment 
descriptor  could  not  be  allocated,  rt  the  partition 
was  not  larqe  enough  to  accoinmod^te  the  region,  or 
there  is  currently  not  enough  continuous  space  m  the 
partition    to    accommodate    the    region. 

The  directive  failed  in  the  attachment  stage  because 
a    region   parity  error   was   detected. 

Attach    failed    because    desir«»d    access    was    not    allowed. 

Specified  partition  In  which  the  region  was  to  be 
allocated  does  not  exist;  or  no  region  name  was 
specified    and    RS.ATT    =    0. 


Part   of    the    DPB   or 
address    space. 


RDB 


out      of      issuing      task's 


lE.SDF      —      Die    or    RDB    size    is    invalid. 


Notes : 


The  Executive  does  not  return  an  error  if  the  named  region 
already  exists.  In  this  case,  the  Executive  clears  the 
RS.CRR  bit  in  the  status  word  R.GSTS.  If  RS.ATT  has  been 
set,  the  Executive  attempts  to  attach  the  already  existing 
naned    region    to    the    issuing    task. 


The    protection    word 
that      of      the       file 
categories,    and    the 
four      bits.         From 
follow    this   order: 


(see  R.GPRO  above)  has  the  same  format  as 
system  protection  word.  There  are  four 
access  for  each  category  is  coded  into 
low  order  to  high  order,  the  categories 
system,  owner,  group,  world.  The  access 
code  bits  within  each  category  are  arranged  (from  low  order 
to  high  order)  as  follows:  read,  write,  extend,  delete.  A 
bit  that  Is  set  indicates  that  the  correspo".d'  7  access  is 
denied . 

The    Issuing    task's    UIC    is    the    created    region's   owner    UIC. 

In  order  to  pre'.-ent  the  creation  of  common  blocks  that  are 
not  easily  deleted,  the  system  anJ  owner  categories  ar" 
always  forced  to  have  delete  access,  rega'dles.?  of  the  value 
actually  specified    in    the    protection    word. 
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CHVT$ 


5.3.14  Create  Virtual  Terminal 

The  Create  Virtual  Terminal  directive  creates  a  virtual  terminal  for 
use  by  a  parent  task  in  communicating  with  its  offspring  tasks.  When 
the  offspring  task  issues  j  read  nr  write  to  its  TI :  terminal,  the 
request  is  sent  to  the  parent  task  through  the  virtual  terminal.  For 
example,  when  the  Batch  Processor  invokes  a  task,  it  communicates  with 
that  task  through  a  virtual  terminal  rather  than  a  physical  terminal. 

This  directive  creates  a  Device  Control  Block  (DCB)  and  a  Unit  Control 
Block  (UCB)  for  each  virtual  terminal  unit,  and  links  t'ne-  unit  to  the 
device  list.  Each  newly  created  virtual  terminal  unit  is  assigned  the 
lowest  available  virtual  terminal  unit  number. 

Only  a  single  copy  of  the  Status  Control  Block  (SCB)  is  required.  The 
data  structure  for  Virtual  Terminal  Unit  0  (VTO: )  is  used  as  a 
template  for  these  dynamically  created  data  structures.  Therefore, 
VTO:   is  never  assigned  as  a  virtual  terminal  unit  number. 

On  successful  coinpletior.  of  this  directive,  the  assigned  VT:  unit 
number  is  returned  in  the  DSW  with  the  Carry  bit  clear.  The  task  must 
save  this  number  if  this  virtual  terminal  is  to  be  referenced  in 
another  directive. 

A  rundown  count  is  maintained  in  the  issuing  task's  TCB  to  indicate 
the  total  (current)  number  of  virtual  terminals  th-  task  has  created 
and  the  number  of  connected  offspring  tasks.  This  count  is  reduced 
when  an  EliminaLe  Virtual  Terminal  directive  is  issued  specifying  this 
VT:   unit. 

The  input  and  output  AST  routines  for  the  virtual  terminal  unit  are 
entered  with  the  following  three  words  on  the  stack: 

SP+04   —  Third  parameter  word  (VFC)  of  offspring  request 
SP+02   —  Byte  count  of  offspring  request 

SP+00   —  Virtual   terminal   unit   number    (low   byte);     I/O 
subfunction  code  of  offspring  request  (high  byte) 

The  attach  and  detach  AST  routines  are  entered  with  the  following 
three  words  on  the  stack; 

SP+04   —  Second  word  of  offspring  task  name  (0  if  detach  AST) 
SP+02   —   First  word  of  offspring  task  name  (0  if  detach  AST) 
SP+OC   —  Virtual   terminal   unit   number    (low   byte);     I/O 
subfunction  code  of  offspring  request  (high  byte) 

Note  that  the  detach  AST  routine  is  entered  with  0  in  both  task  name 
words  on  the  stack.  The  AST  routine  must  remove  t-he  three  words  from 
the  stack  before  it  issues  an  AST  Service  Exit  directive. 

Parent  tasks  can  service  each  offspring  input  or  output  request  with  a 
corresponding  output  or  input  request  to  the  correct  virtual  device 
unit.  For  example,  where-  Macro-11  has  been  activated  as  an  offspring 
task  of  the  Batch  Processor  with  a  TI:   of  VT3: 

1.  Macro-11  issues  an  lO.RVB  or  lO.RLB  to  TI:  for  its  first 
input  line.  The  virtual  terminal  driver  queues  the  read 
request  internally  and  effects  an  AST  in  the  Batch  Processor 
at  the  virtual  address  "iast"  with  the  unit  number  3  and  the 
byte  count  fmm  Macro-11 's  I/O  request  on  the  stack. 
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2.  In  its  AST  routine,  the  Batch  Processor  retrieves  an  input 
line  for  Macro-11  from  the  Batch  stream  and  specifies  this 
line  In  a  QIO  directive  to  a  LUN  assigned  to  VT3:  with  an 
lO.WVB  or  lO.WLB  function,  a  byte  count  of  the  line,  and  the 
status  to  be  returned  (such  as  IS.CR). 

3.  The  virtual  terminal  driver  reads  the  line  from  the  Batch 
Processor's  buffer,  writes  the  line  to  Macro-11's  buffer,  and 
then  signals  I/O  completion  for  both  I/O  requests. 

4.  Similarly,  if  Macro-11  needs  to  print  an  error  message,  it 
does  so  with  an  lO.WVB  or  lO.WLB  to  TI : .  The  virtual 
terminal  driver  queues  the  write  request  internally  and 
effects  an  AST  in  the  Batch  Processor  at  the  virtual  address 
"oast"  with  the  unit  number  3,  the  byte  count,  and  the  VFC 
from  Macro-11's  I/O  request  on  the  stack. 

5.  In  its  output  AST  routine,  the  Batch  Processor  Issues  an 
lO.RVB  or  10. RLE  to  retrieve  the  line  by  means  of  the  virtual 
terminal  driver.  The  Batch  Processor  may  then  output  this 
line  to  its  log  file.  The  third  word  on  the  AST  stack  in  the 
Batrh  output  AST  routine  is  the  vertical  format  character, 
telling  Batch  what  type  of  cTrriage  control  is  expected  for 
the  output  line.  This  word  would  be  ignored  in  the  input  AST 
rout  ine . 


Intermediate  buffering  in  secondary  pool,  when  enabled  by  the  parent 
task,  is  performed  on  offspring  Input  and  output  requests  when  the 
offspring  task  is  checkpointable.  Offspring  tasks,  therefore,  may  be 
stopped  and  checkpo inted .  If  the  parent  task  is  stopped  and 
checkpointed  when  the  offspring  task  issues  an  J/0  request,  the 
resulting  AST  brings  the  parent  task  to  an  unstopppJ  state  from  which 
it  may  return  to  memory  to  service  the  I/O  request.  Upon  exit  from 
the  AST  routine,  the  parent  task  is  again  stopped.  This  mode  of 
operation  allows  the  parent  and  offspring  tasks  to  share  the  same 
physical  memory,  even  while  the  parent  task  services  the  terminil  I/O 
requests  for  the  offspring  task.  Whenever,  for  any  reason,  the 
virtual  terminal  driver  determines  that  is  should  not  use  intermediate 
buffering,  offspring  tasks  are  locked  in  memory  when  I/O  requests  .ire 
issued,  and  transfers  occur  directly  between  parent  and  offspring 
buffers. 

The  intermediate  buffering  of  -jffspring  I/O  requests  can  normally  be 
enabled  and  disabled  by  the  parent  task  by  th«^  lO.STC  function,  as 
described  below.  An  exception  to  this  exists  for  virtual  terminals 
created  with  a  "mien"  parameter  greater  than  a  system-wide  maximum 
specified  at  Sysgen  time.  (Sysqen  does  not  allow  this  maximum  to  be 
greater  than  512.)  If  a  Create  Virtual  Terminal  directive  is  specified 
with  a  "mien"  parameter  greater  than  the  system-wide  maximum,  the 
parameter  Is  accepted,  but  intermediate  buffering  for  the  creeled 
virtual  terminal  unit  is  automat  i<5al  ly  disabled.  Furthermore, 
intermediate  buffering  for  that  unit  cannot  be  enabled  by  the  parent 
task  by  the  10  STC  function. 
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Parent  tasks  specify  the  first  word  of  the  I/O  completion  status  for 
the  offspring  request  in  the  thirJ  word  of  the  QIO  DPB .  For  example, 
consider  an  offspring  input  request  for  10  characters  or  more  that  Is 
honored  with  a  write  logicil  of  10  characters  and  IS.CR  in  the  third 
parameter  word.  The  second  word  of  the  I/O  status  would  be  set  to  10 
and  10  characters  would  be  transferred.  Another  example  Is  when  a 
parent  task  issues  a  read  request  to  satisfy  a  write  request  that  was 
issued  by  the  offspring  task.  To  notify  the  offspring  task  that  its 
write  request  was  satisfied  the  parent  task  would  specify  IS.SUC  in 
the  third  parameter  word. 

ft  special  I/O  function,  lO.STC,  returns  status  to  an  offspring  task 
without  a  data  transfer.  The  parameter  word  format  for  the  lO.STC 
function  is  as  follows: 

•  Word  0  with  bit  0  set  indicates  that  status  is  being  returned. 

•  Word  0  with  bit  1  clear,  if  the  virtual  terminal  is  in 
full-duplex  mode,  indicates  that  status  is  being  returned  for 
an  offspring  read  request. 

•  Word  0  with  bit  1  set,  if  the  virtual  terminal  is  in 
full-duplex  mode,  indicates  that  status  is  being  returned  for 
an  offspring  write  request. 

NOTE 

If   the  virtual    terminal    is   in 
half-duplex  mode,  bit  1  is  ignored. 

•  Word  1  is  the  second  word  of  I/O  return  status. 

•  Word  2  is  the  first  word  of  I/O  return  status. 

The  status  words  are  reversed  in  order  to  be  similar  to  the  format  in 
which  status  must  be  passed  back  in  a  parent  read  or  write  fi'iction  to 
an  offspring  task.  The  lO.STC  function  must  be  used  to  return  status 
when  no  transfer  is  desired,  since  a  byte  count  of  0  is  not  allowed  in 
an  lO.RLB  or  lO.WLB  (read  logical  block  and  write  logical  block 
operations,  respectively).  For  example,  IE. EOF  (write  end-of-file 
tape  mark),  would  normally  be  returned  with  lO.STC. 

Note  that  it  is  important  to  specify  an  I/O  completion  status  for  all 
parent  read  and  write  requests  that  satisfy  corresponding  requests 
from  the  offspring  task.  If  a  return  status  is  not  specified,  it 
defaults  to  zero.  A  zero  indicates  that  the  I/O  is  still  pending 
(IS.PND).  This  causes  the  offspring  task  to  hang  if  it  examines  the 
I/O  status  block  to  determine  whether  the  I/O  is  completed. 

In  addition  to  returning  status,  the  lO.STC  function  has  an  additional 
purpose.  It  can  enable  or  disable  intermediate  buffering  of  I/O 
requests;  note  that  a  task  cannot  perform  both  lO.STC  functions  in 
the  same  I/O  request.  If  bit  0  of  the  first  parameter  word  in  lO.STC 
is  clear,  bit  1  in  this  word  is  interpreted  as  a  disable  buffering 
flag: 

•  If  hit  0  is  clear  and  bit  1  is  set,  intermediate  buffering  of 
offspring  I/O  is  disabled. 

•  If  bit  0  is  clear  and  bit  1  is  clear,  buffering  is  enabled. 
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Buffering  cannot  be  enabled  on  a  virtual  terminal  unit  that  has  been 
created  with  an  "mien"  parameter  greater  than  the  system-wide  maximum 
specified  at  Sysgen  time.  An  attempt  to  do  both  results  in  an  error 
return  of  IE. IPC. 

The  only  tasks  that  can  assign  LUNs  to  a  virtual  terminal  unit  are: 

•  The  task  that  created  the  virtual  terminal  unit 

•  That  task's  offspring   task(s),   whose   TI:    is   the   virtual 
terminal  unit 

Attachment  of  a  virtual  terminal  unit  by  an  offspring  task  prevents 
the  dequeuing  of  I/O  requests  to  that  unit  from  other  offspring  tasks; 
parent  I/O  requests  are  always  serviced. 

Both  parent  and  offspring  tasks  can  specify  the  I/O  functions  10. GTS, 
SF.GMC,  and  SF.SMC.  However,  SF.GMC  and  SF.SMC  support  only  a  limited 
number  of  terminal  characteristics  for  virtual  terminals.  Please 
refer  to  the  RSX-1 IM/M-PLUS  I/O  Drivers  Reference  Manual  for  a  list  of 
valid  characteristics. 


Note  that  the  parent  task  is  not  notified  when   the   offspring 
any  of  the  above  directives. 


Issues 


When  an  offspring  task  issues  a  read-wl th-prompt  request  {10. RPR),  the 
virtual  terminal  driver  separates  the  request  into  an  lO.WLB  request 
and  an  lO.RLB  request.   The  parent  task  cannot  issue  an  10. RPR. 

When  a  virtual  terminal  is  :n  half-duplex  mode,  the  virtual  terminal 
driver  handles  only  one  offspring  request  at  a  time.  For  example,  if 
the  offspring  task  issues  a  read  request  and  then  issues  a  write 
request  without  waiting  for  the  read  to  be  completed,  the  driver 
queues  the  write  request  to  be  processed  when  the  re  id  is  completed. 

The  parent  task  may  issue  an  SF.SMC  function  to  set  the  virtual 
terminal  to  full-duplex  mode.  In  full-duplex  mode,  the  write  request 
in  the  previous  example  would  be  processed  even  if  the  previous  read 
was  not  yet  completed.  If  the  parent  task  is  at  AST  st^te,  It  will 
not  receive  notification  of  the  I/O  request. 

Both  pirent  and  offspring  tasks  can  issue  an  SF.GMC  request  to 
determi.Te  the  mode  of  the  virtual  terminal.  However,  only  the  parent 
task  can  change  the  mode  (using  SF.SMCi . 

FORTRAN  Call : 

CALL  CRVT  ( [  I  lastl , [  loast ] , [ iaast ] , [ imlen] , I parm, ( Ids] ) 

iiast  =  AST  address  at  which  input  requests  from  offspring 
tasks  are  serviced 

ioast  =  AST  address  at  which  output  requests  from  offspring 
tasks  are  serviced 

iaast  =  AST  address  at  which  the  parent  task  may  be  notified 
of  the  completion  of  successful  offspring  attach  and 
detach  requests  to  the  virtual  terminal  unit 


NOTE 

At  least  one  of  the  above  optional 
parameters  should  be  specified; 
otherwise,  the  virtual  terminal  created  Is 
treated  as  the  null  device. 
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Imlen 

iparm 

ids 

Macro  Call  : 
CRVT$ 
last 

oast 

aast 


Maximum   buffer   length  allowed   for  offspring   I/O 
requests 

Address  of  3-word  buffer  to  receive  Information   from 
the  stack  when  an  AST  occurs 

Integer   to   receive   the   directive   status   word 
containing  the  virtual  terminal  number 


[last] , [oast] , [aast] , [mien] 

■»  AST  address  at  which  input  requests  from  offspring 
tasks  are  serviced.  If  iast=0,  offspring  Input 
requests  are  rejected  with  lE.IFC  returned. 

»  AST  address  at  which  output  requests  from  offspring 
tasks  are  serviced.  If  oast«0,  offspring  output 
requests  are  rejected  with  IE.  IPC  returned. 

■  AST  address  at  which  the  parent  task  may  be  notified 
of  the  completion  of  successful  offspring  attach  and 
detach  requests  to  the  virtual  terminal  unit.  If 
aast=0,  no  notification  of  offspring  attach/detach  is 
returned  to  the  parent  task. 


NOTE 

At      least      one      of      the        above        optional 
parameters  should  be  specified; 

otherwise,    the    virtual    terminal    created    is 
treated    as   the   null    device. 


mien  =  Maximum  buffer  length  (bytes)  allowed  for  offspring 
I/O  requests  (Jefault  and  maximum  values  for  this 
parameter   are   SYSGEN  options) . 


Macro    Expansion: 

CRVT$ 

.BYTE  149., 5 

.WORD  lASTRU 

.WORD  OASTRU 

.WORD  PAST 


lASTRU, OASTRU, PAST, 20. 


.WORD 
Local    Symbol 
C.RVIA 
C . RVOA 
C . RVAA 
C.RVML 


CRVT$    MACRO    DIC,     DPB    SIZE=5    WORDS 
INPUT    REQUEST    AST    ROUTINE    ADDRESS 
OUTPUT    REQUEST    AST    ROUTINE    ADDRESS 
SUCCESSFUL    VT    ATTACH    NOTIFICATION    AST 
ROUTINE    ADDRESS 
MAXIMUM    BUFFER    LENGTH    =    20. BYTES 


20. 
Definitions : 

Input  request  AST  routine  address  (2) 
—   Output  request  AST  routine  addres.^  (2) 

VT  attach  notification  AST  routine  address  (2) 

Maximum  buffer  length  (2) 
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DSW  Return  Codes: 

unit  —  Successful  con.  '.  .Ion  results  In  the  return  of  the 
unit  number  of  the  created  virtual  terminal  unit  with 
the  C  bit  clear . 

lE.UPN  --  Insufficient  dynamic  memory  to  allocate  the  virtual 
terminal  device  unit  data  structures. 

lE.HWR   —  Virtual  terminal  device  driver  not  resident. 

lE.ADP  —  Part  of  the  DPB  is  out  of  the  issuing  task's  address 
space. 

lE.SDP   --   Die  or  DPB  size  Is  invalid. 
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5.3.15   Cancel  Time  Based  Initiation  Requests 

The  Cancel  Time  Based  Initiation  Requests  directive  Instructs  the 
systeir  to  cancel  all  time-synchronized  initiation  requests  for  a 
specified  task,  regardless  of  the  source  of  each  request.  These 
requests  result  from  a  Run  directive,  or  from  any  of  the 
time-synchronized  variations  of  the  MCR  or  tX.'L  Hun  command. 

In  a  multiuser  protection  system,  a  nonpr 1 v 1 1 eqed  task  can  cancel 
time-based  initiation  requeats  only  for  a  task  with  the  same  TI:. 

FORTRAN  Call : 

CALL  CANALL  (tsk! , ids) ) 

tsk   =   Task  namt 

Ids   =   Directive  status 

Macro  Cal  1  : 

CSRO$    tsk 

tsk   =   Scheduled  (target)  task  name 

Macro  Expansion: 

CSRO$         ALPHA 

•  BYTE         25.,  (  ;CSRO$    MACRO    DIC,     DPB    SIZE-3    WORDS 

.RAD50       /ALPHA/  ;TASK    "ALPHA" 

Local    Symbol    Definitions: 

C.SRTN      -~      Target    task   name    f4) 
DSW    Return    Codes: 

IS. sue      --      Successful    completion. 

IE.  INS      --      Task    is    not    installed. 

lE.PRI      --      The    issuing    task    is   not    privileged    and    Is      attempting 
to    cancel    requests   made    by   another    task. 

lE.ADP      --      Part   of    the    DPB    is   out    of    the    issuing    task's      address 
s  pa  c  e  . 

lE.SDP      —      DIC    or    DPB    size    is    Invalid. 

Note: 

If  you  specify  an  error  routine  address  when  using  the  $C  or  OS 
macro  form,  then  you  must  include  a  null  argument  for  RSX-llD 
compatibility        For    example: 

CSRQSS  »TNAME,,ERR  .-CANCEL    REQUESTS    FOR    "ALPHA" 


TNAME:     . RAD50       /ALPHA/ 
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DECL$ 


5.3.16   Declare  Significant  Event  ($S  Form  Recommended) 

The  Declare  Significant  Event  directive  instructs  the  system  to 
declare  a  significant  event. 

Declaration  of  a  significant  event  causes  the  Executive  to  scan  the 
Active  Task  List  from  the  beginning,  searching  for  the  highest 
priority  task  that  is  ready  to  run.  Use  this  directive  with 
discretion  to  avoid  excessive  scanning  overhead. 

FORTRAN  Call : 

CALL  DECLAR  ([  ,idsl  ) 

ids   =   Directive  status 

Macro  Cal 1 : 

DECL$S       [,errl 

err      =      Error    routine   address 

Macro    Expansion: 


DECL$S  , ERR 

MOV  (PC)+,-(SP) 

.BYTE  15., 1 

EMT  377 

BCC  .+6 

JSR  PC, ERR 


NOTE:       THERE    IS    ONE    IGNORED   ARGUMENT 

PUSH    DPB    ONTO    THE    STACK 

DECL$S    MACRO    DIC,     DPB    SIZE=1    WORD 

TRAP   TO    THE    EXECUTIVE 

BRANCH    IF    DIRECTIVE    SUCCESSFUL 

OTHERWISE,     CALL    ROUTINE    "ERR" 


Local    Symbol    Definitions: 

None 
DSW    Return    Codes: 

IS. sue      —     Successful    completion. 

lE.ADP      —      Part   of    the      DPB    is    out   of    the    issuing    task's   address 
space . 


Note 


TE.SDP      —      DIC    or    DPB    size    is    invalid 


The    $S    form   of    the   macro    is    recommended      because      this      directive 
requires  only  a    1-word    DPB. 
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IHAR$S 


5.3.17   Disable  (or  Inhibit)  AST  Recognition  ($S  Form  Recommended) 

The  Disable  (or  Inhibit)  AST  Recoynition  directive  instructs  the 
system  to  disable  recognition  of  ASTs  for  the  issuing  task.  The  ASTs 
are  queued  as  they  occur  and  are  effected  when  the  task  reenables  AST 
recognition.  There  is  an  implied  disable  AST  recoy  ni  t  ic.i  directive 
whenever  an  AST  service  routine  is  executing.  When  a  task's  execution 
is  started,  AST  recognition  is  enabled.   See  Notes  below. 

FORTRAN  Call : 

CALL  DSASTR   (  (ids) ] 

or 
CALL  INASTR   [ (ids) ) 

ids   =   Directive  status 
Macro  Call : 

DSARSS   [err] 

err   =   Error  routine  address 
Macro  Expansion: 


DSAR$S  ERR 

MOV  (PC)+,-(SP) 

.BYTE  99., 1 

EMT  377 

BCC  .+6 

JSR  PC, ERR 


PUSH  DPS  ONTO  THE  STACK 

DSARSS    MACRO    DIC,     DPS    SIZE=1    WORD 

TRAP    TO    THE    EXECUTIVE 

BRANCH     IF    DIRECTIVE    SUCCESSFUL 

OTHERWISE,  CALL  ROUTINE  "ERR" 


Local  Symbol  Def'   "ions: 

None 
DSW  Return  Codes: 

IS. sue   —  Successful  completion. 

IE. ITS   —  AST  recognition  is  already  disabled. 


lE.ADP 


Part  of  the   DPB  is  out  of  the  issuing  task's  address 
space  . 


lE.SDP   --  DIC  or  DPB  size  is  invalid. 
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Notes; 


1.  This  directive  disables  only  the  recognition  of  ASTs ;  the 
Executive  still  queues  the  ASTs.  They  are  queued  FIFO  and 
will  occur  in  that  order  when  the  task  reenables  AST 
recogni t  ion . 

2.  The  FORTRAN  calls,  DSASTR  (or  INASTR)  and  ENASTR  (see  Section 
5.3.24),  exist  solely  to  control  the  possible  jump  to  the 
PWRUP  routine  (power-up).  FORTRAN  is  not  designed  to  link  to 
a  system's  trapping  mechanism.  The  PWRUP  routine  is  strictly 
contiolled  by  the  system,  which  both  accepts  the  trap  and 
subsequently  dismisses  it.  The  FORTRAN  program  is  notified 
by  a  jump  to  PWRUP  but  must  use  DSASTR  (or  INASTR)  and  ENASTR 
to  f.-nsure  the  integrity  of  FORTRAN  data  structures,  most 
importantly  the  stack,  during  power-up  processing. 

3.  Because  this  Jirective  requires  only  a  1-word  DPB,  the  $S 
form  of  the  macro  is  recommended.  It  requires  less  space  and 
executes  with  the  same  speed  as  that  of  the  DIR$  macro. 
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5.3.18   Disable  Checkpointing  {$S  Porn  Recommended) 

The  Disable  Checkpointing  directive  instructs  the  system  to  disable 
the  checkpointabil ity  of  a  task  that  has  been  installed  as  a 
checkpointable  task.  Only  the  affected  task  can  issue  this  directive. 
A  task  cannot  disable  the  ability  of  another  task  to  be  checkpo inted . 

FORTRAN  Call : 

CALL  DISCKP  [  (ids) ] 

Ids   =   Directive  status 

Macro  Cal 1 : 

DSCPSS   [err] 

err   =   Etror  routine  address 

Macro  Expansion: 


DSCPSS  ERR 

MOV  (PC)+,-(SP) 

.BYTE  95.,  I 

EMT  377 

BCC  .+6 

JSR  PC, ERR 


PUSH  DPS  ONTO  THE  STACK 

DSCPSS    MACRO    DtC,     DPB    S1ZE=1    WORD 

TRAP    TO    THE    EXECUTIVE 

BRANCH    IF    DIRECTIVE    SUCCESSFUL 

OTHERWISE,  CALL  ROUTINE  "ERR" 


Local  Symbol  Definitions: 

None 
DSW  Return  Codes: 

IS. sue   —  Successful  completion. 

IE. ITS   —   Task  che-^kpo  int  i  nq  is  already  disabled 
-   Issuing  task  is  not  checkpointable. 


lE.CKP 
lE.ADP 


lE.SDP 
Notes : 

1 


--   Part  of  the  DPB  is  out  of  the  issuing  task's  address 
space. 

—   Die  or  DPB  size  is  invalid. 


When  a  checkpointable  task's  execution  Is  started, 
checkpointing  is  enabled  (that  is,  the  task  can  be 
checkpo  inted)  . 

Because  this  directive  requires  only  a  1-word  DPB,  the  Ss 
form  of  the  macro  Is  recommended.  It  requires  less  space  and 
executes  with  the  same  speed  as  that  of  the  DIRS  macro. 
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5.3.19   Detach  Region 

The  Detach  Region  directive  detaches  the  issuing  task  from  a 
specified,  previously  attached  region.  Any  of  the  task's  windows  that 
are  currently  mapped  to  the  region  are  automatically  unmapped. 

If  RS.MDL  is  set  in  the  region   status   word   when   the   directive   is 

issued,   the  task  marks  the  rtjion  for  deletion  on  the  last  detach.   A 

task  must  be  attached  with  delete  access  to  mark  a  region  for 
deletion . 

FORTRAN  Call : 

CALL  DTRG  (irdb( ,ids; * 

irdb      =      An    8-word    irteger    array   containing    a    Region    Definition 
Block    (s  :^  ion    3. S.  1. 2) 

ids         =      Directive    iy^^tis 
Macro    Cal  1  : 

DTRGS  rdfc 

rdb      =      Region    Definition    Block    address 

Macro    Expansion: 

DTRGS         RDBADR 

.BYTE  59., 2  ;DTRGS    MACRO    DIG,     DPB    SIZE=2    WORDS 

.WORD         RDBADR  ;RbB    ADDRESS 

Region    Definition    Block    Parameters: 

Input    parameters: 

Array  Offset 

Element 

irdb(l)   R.GTD    --   ID  of  the  region  to  be  detached 

irdb(7)   R.GSTS   —   Bit  settings^  in  the  region  status  worl: 

Bit  Def init  ion 

RS.MDL  1  if  the  region  should  be  marked 
for  deletion  when  the  last  task 
detaches  from  it 


1.  If  you   are   a   FORTRAN   programmer,   refer   to   Section   3.5.1   to 
determine  the  bit  values  represented  by  the  symbolic  names  described. 
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Output  parameters: 

lrdb(7)   R.GSTS   --   Bit  settings^  In  the  recjlon  status  word: 

Bit  Definition 

RS.UNM     1  if   any   windows   w»re  unmapped 
Local  Symbol  Definitions: 

D.TRBA   •--   Region  Definition  Block  address  (2) 
DSW  Return  Codes: 

IS. sue   —   Successful  completion. 


IE. PR  I 


lE.NVR 


lE.ADP 


lE.SDP 


The  task,  which  is  not  attached  with  delete  access, 
has  attempted  to  mark  the  region  for  deletion  on  the 
last  detach,  or  the  task  has  outstanding  1^0  (not 
necessarily  to  this  region  on  RSX-llM  systems  only). 

The  task  specified  an  Invalid  region  ID  or  attempted 
to  detach  region  0  (Its  own  task  region). 

Part  of  the  DPD  or  RDB  Is  out  of  the  Issuing  tark's 
address  space. 

Die  or  DPB  size  is  inval id. 


1.  If  you   are   a   FORTRAN   programmer,   refer   to   Section   I.S.l   to 
determine  the  bit  values  represented  try  the  symbolic  names  described. 
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5.3.20   Eliminate  Address  Window 

The  Eliminate  Address  Window  directive  deletes  an  existing  address 
window,  unmapplng  It  first  if  necessary.  Subsequent  use  of  the 
eliminated  window's  ID  is  Invalid. 

FORTRAN  Call : 

CALL    ELAW    (  lwdb[  ,idsl  ) 

iwdb      =      An    8-word    integer    array   containing    a   Window   D'finitlon 
Block    (336    Section    1.5.2.2) 

Ida        =      Directive    status 
Macro   Cal 1  : 

ELAWS        wdb 

wdb      «      Window    Definition    Block   address 

Macro    Expansion: 

ELAWS         WDBADR 

.BYTE         119., 2  ; ELAWS    MACRO    DIC,     DPB    SIZE-2    WORDS 

.WORD        WDBADR  :WDB    ADDRESS 

Window   Definition    Block    Pirameters: 

Input   parameters: 

Array  Offset 

Eleident 

iwdb(l)  W.NID         --      ID   of    the    address    window    to    be    eliminated 

bits    0-7 

Output    parameters 

iwdb(7)  W.NSTS      --      Bit    settings^    in    the    window  status    word: 

Bit  Definition 

WS.ELW       1  if  the  address   window   was 
successfully  eliminated 

WS.UNM       1  If  the  addres-i   window   was 
unmapped 


1.  If  you   are   a   FORTRAN   programmer,   refer   to   Section   .1.5.2   to 
determine  the  bit  values  represented  by  the  symbolic  names  describe^. 
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Local    Symbol    Definitions: 

E.LABA      —     Window   Definition    Block    address    (2) 
DSW   Return    Codes: 

IS. sue      —     Successful    completion. 

lE.NVW      —      Invalid    address   window   ID. 

lE.ADP      —      Part      of    the      DPB   or   WDB    is   out   of    the    issuing    task's 
address   space. 

lE.SDP      --      Die   or    DPB    size    is    invalid. 
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5.3.21   Eliminate  Group  Global  Event  Flags 

The  Eliminate  Group  Global  Event  Flags  directive  marks  group-global 
event  flags  for  deletion.  If  no  tasks  in  this  group  are  using  the 
group-global  event  flags  (the  use  count  for  this  group  maintained  by 
the  Executive  in  G.CNT  is  0),  the  Group  Global  Event  Flags  Control 
Block  (GFB)  is  immediately  unlinked  and  deallocated.  If  tasks  are 
using  flags  in  this  group,  the  Executive  marks  the  flags  for  deletion 
(GS.DEL  is  set  to  1)  and  the  GFB  is  eliminated  when  no  remaining  tasks 
are  using  the  flags  in  this  group;  however,  i ""  a  Create  Group  Global 
Even'  Flags  directive  is  issued  before  the  flags  are  eliminated,  the 
Executive  clears  GS.DEL. 

If  the  specified  group  code  matches  the  group  code  of  the  issuing 
task's  protection  UIC  and  the  event  flags  are  locked  by  this  task  (by 
a  previous  Create  Group  Global  Event  Flags  directive),  this  directive 
unlocks  the  event  flags  by  decrementing  the  access  count.  Note  that  a 
task  may  not  unlock  the  event  flags  more  than  once  in  succession.  Any 
attempt  to  unlock  event  flags  that  are  already  unlocked  will  return 
the  lE.RSU  error  code. 

FORTRAN  Call : 

CALL  ELGF  ( [group]  [,  Ids] ) 

group  =  Group  number  of  flags  to  be  eliminated.  Only 
privileged  tasks  can  specify  group  numbers  other  than 
the  issuing  task's  group  UIC.  If  not  specified,  the 
task's  protection  UIC  (H.CUIC+1)  ir  the  task's  header 
is  used. 

ids     =   Integer  to  receive  the  Directive  Status  Word. 

Macro  Call  : 

ELGFS         [group] 

group      =     Group     number      of      flags      to      be      eliminated.  Only 

privileged  tasks  can  specify  gr^up  numbers  other  than 
the  issuing  task's  group  UIC.  If  not  specified,  the 
task-s  protection  UIC  (H.CUIC+1)  in  the  task's  header 
is    used. 

Macro  Expansion: 

ELGF$  303 

.BYTE  159., 2  ;ELGF$   MACRO    DIC,    DPB    SIZE=2    WORDS 

.WORD  303  ;GROUP   NUMBER    303    FLAGS 

Local    Symbol    Definitions: 

E.LGRF    •-  Group  number    (2) 
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DSW    Return    Codes: 

IS. sue   —  Successful    completion. 

lE.PRI    --   Privilege   violation. 

lE.IUI    —   Invalid   group    (gro.-i>377   octal). 

lE.IEF    —  Group    is   not    found. 

lE.RSU    --   Event    flags   are    already  marked    for   deletion. 

lE.ADP    —   Part    of    the    DPB    is   out   of    the      issuing      task's      address 
space. 

IE. Die    —  DIG   or    DPB   size    is    invalid. 
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5.3.22   Eliminate  Virtual  Terminal 

The  Eliminate  Virtual  Terminal  directive  causes  the  specified  virtual 
terminal  unit  data  structures  to  be  marked  for  deallocation  and 
eventually  to  be  unlin'ced  from  the  device  list  and  deallocated.  This 
directive  can  only  be  issued  by  the  task  that  created  the  virtual 
terminal  device  unit.  Any  active  nonpr ivileged  tasks  are  aborted 
whose  TI:  device  units  are  the  virtual  terminal  being  deallocated. 
TKTN  messages  reporting  the  abort  of  these  tasks  In  this  instance  are 
directed  to  CO:.  Any  LUNs  assigned  by  the  issuing  task,  or  by  any 
offspring  task  being  aborted,  are  deassigned. 

A  rundown  count  is  maintained  in  the  TCB  of  each  parent  task.  This 
count  reflects  the  total  number  of  outstanding  virtual  terminal  units 
the  task  has  created,  plus  the  number  of  connected  (offspring)  tasks. 
A  series  of  ELVT$  directives  are  issued  when  a  parent  task,  which  has 
not  eliminated  virtual  terminals  it  has  created,  exits.  The  virtual 
terminal  data  structures  continue  to  exist  until  the  last  task  exits 
whose  TI :  is  the  virtual  terminal  unit  and  until  all  CLI  commands  for 
that  unit  have  been  processed. 

FORTRAN  Call: 

CALL  ELVT  ( i unum ( , ids] ) 

iunum   =   Virtual  terminal  unit  number 

ids    =   Integer  to  receive  the  Directive  Status  Word 

Macro  Cal 1  : 

ELVTS    unum 

unum  =  Unit  number  of  the  virtual  terminal  to  be  eliminated. 
The  task  must  provide  this  parameter  after  the 
virtual  terminal  is  created  (see  Note). 

Macro  Expansion: 

) 

;ELVT$    MACRO    DIC,     DPB    SIZE=2    WORDS 
;VIRTUAL   TERMINAL    UNIT    NUMBER 

Local    Symbol    Definitions: 

E.LVNM      --      VT   unit    number    (2) 
DSW    Return    Coies: 

IS. sue   —   Successful  completion. 

lE.IDU   —   The  specified  virtual  terminal  unit  does  not  exist  or 
it  was  not  created  by  the  issuing  task, 

lE.ADP   --   Part  of  the  DPB  is  out   of  the  issuing  task's  address 
space. 

IE. SOP   —   DIC  or  DPB  size  is  invalid. 


ELVTS 

0 

.BYTE 

151. 

,2 

.WORD 

0 
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Note: 


The  actual  virtual  terminal  unit  number  is  not  known  until  after 
the  v'rtual  terminal  is  actually  created  (that  is,  after 
successfully  completing  a  Create  Virtual  Terminal  directive). 
The  Create  Virtual  Terminal  directive  DSW  contains  the  actual 
virtual  terminal  unit  number  for  use  In  the  Eliminate  Virtual 
Terminal  directive.  Thus,  the  task  must  save  DSWs  for  all 
virtual  terminals  it  creates,  and  later  eliminate  them  using  the 
Eliminate  Virtual  Terminal  Directive. 
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5. 3. 23   Emit  Status 

The  Emit  Status  directive  returns  the  specified  Ifi-blt  quantity  to  the 
specified  connected  task.  It  possibly  sets  an  event  flaq  or  declares 
an  AST  if  previously  specified  by  the  connected  task  in  a  Send, 
Request  And  Connect,  a  Spawn,  or  a  Connect  directive.  If  the 
specified  task  is  multiply  connected  to  the  task  issuing  this 
directive,  the  first  (oldest)  Offspring  control  Block  (OCB)  In  the 
queue  is  used  to  return  status.  If  no  task  name  Is  specified,  this 
action  is  taken  for  all  tasks  that  aro  connected  to  the  issuing  task 
at  that  time.  In  any  case,  whenever  status  is  emitted  to  one  or  more 
tasks,  those  tasks  no  longer  remain  connected  to  the  task  issuing  the 
Emit  Status  directive. 

FORTRAN  Cal I : 

CALL  EMST  ( f rtname] , status [, Ids] ) 

rtiiame   =   Name  of  a  task  connected   to   the   issuing   task   to 
which  the  status  is  to  be  emitted 

status   I-   A  16-blt  quantity  to  be  returned   to   the   connected 
task 


ids 
Macro  Ca 1 1 : 
EMSTS 


Integer  to  receive  the  Directive  Status  Word 


[tname] , status 


tname    =   Name  of  a  task  connected   to   the   issuing   task   to 
which  the  status  Is  to  be  emitted 


status 
Macro  Expansion 


16-bit  quantity  to  be  returned  to  the  connected  task 


EMSTS 

ALPHA, STWD 

.BYTE 

1  4  7  .  ,  4 

.RAD50 

ALPHA 

.WORD 

STWD 

EMST$  MACRO  CIC,  DPB  SIZE=«4  WORDS 

NAME  OF  CONNECTED  TASK  TO  RECEIVE  STATUS 

VALUE  OF  STATUS  TO  BE  RETURNED 


Local  Symbol  Definitions: 

E.MSTN   --   Task  name  (4) 

E.MSST   --   Status  to  be  returned  (2; 
DSW  Return  Codes: 

IS. sue   —   Successful  completion. 


IE. ITS 


TE.ADP 


n:.SDP 


The  specified  task  is  not  connected   to   the   issuing 
task. 

Part  of  the  DPB  is  out  of  the  issuing  task's   address 
space . 

Die  or  DPB  size  is  invalid. 
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ENARSS 


S.1.24   Enable  AST  Recognition  ($S  Korn  Kecoamended) 


is,  the  d  i  rect  ive 
that  were  queued 
issuanre.  When  a 
ed. 


system  to  recognize 

nul 1  I f ies  a  Di  sabl e 

wh  i 1 e   recogni  t  ion 

task's  execution  is 


The  Enable  AST  Recognition  directive  instructs  the 
ASTs  for  the  issiuing  task;   that 
AST  Recognition  directive.   ASTs 
was   disabled   are   effected   at 
started,  AST  recognition  is  enab; 

FORTRAN  Cal I : 

CALL  ENASTR   [  (ids)  I 

ids   =   Directive  status 

Macro  ■'all: 

ENARSS   [err] 

err   =   Error  ro  .*  '    ildress 

Macro  Expansion: 

ENARSS  ERR 

MOV  (PC)«-,-(SP) 

.BYTE  101. ,1 

EMT  377 

BCC  .+6 

JSR  PC, ERR 

Local    Symbol    Definitions: 

None 
DSW    Return    Codes: 

IS.  sue      —      Suc'-'essful    completion. 

IE. ITS      --      AST    reco:]ni  t  io.i    is    not    (ii^ahlod. 

lE.ADP      --      Part    of    the    DPB    is   out    of    the    issuing    task's      address 
space . 


PUSH    DPB    ONTO    THE    STACK 
ENARSS    MACRO    DIC,     DPB    SIZE-l    WORD 
TRAP   TO    THE    EXECUTIVE 
BRANCH    IF    DIRECTIVE    SUCCESSF'JL 
/OTHERWISE,    CALL    ROUTINE    "ERR" 


lE.SDP 


Die  or  DPB  size  is  invalid 


Notes ; 


1.  Because  this  iirective  requires  only  n  l-word  DPB,  the  SS 
form  of  the  macro  is  recommended.  It  requires  less  space  and 
executes  with  the  same  speed  as  that  of  the  DIRS  macro. 

2.  The  FORTRAN  calls  DSASTR  Or  INASTR)  (see  Section  S.1.17)  and 
ENASTR  exist  solely  to  control  the  jump  to  the  PWRUP  routine 
(power-up).   FORTRAN  is  not  designed  to  link   to   a   system's 


» 


t'-appinq  mechanism 
by  the  system.   It 
and   subsequently 
notified  by  a  jump 
and    ENASTR    to 
structures,   most 
processing  . 


The  PWRUP  routine  is  strictly  controlled 
Is  the  system  that  botli  accepts  the  trap 
dismisses  It.  The  FORTRAN  program  Is 
to  PWRUP  but  must  use  DSASTR  (o'  INASTR) 
ensure  the  integrity  of  FORTRAN  data 
importantly   the   stack,   luring   prwer-iip 
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5.3.25   Enable  Checkpointing  ($S  Form  Recommended) 

The  Enable  Checkpointing  directive  instructs  the  system  to  make  the 
issuing  task  checkpointable  after  its  checkpo intabil i ty  has  been 
disabled;  that  is,  the  directive  nullifies  a  DSCP$S  directive.  This 
directive  cannot  be  used  to  enable  checkpointing  of  a  task  that  was 
built  noncheckpo intable . 

FORTRAN  Call  : 

CALL  ENACKP  [ (ids) ] 

ids   =   Directive  status 

Macro  Cal 1 : 

ENCPSS   [err] 

err   =   Error  routine  address 

Macro  Expansion: 


ENCP$S  ERR 

MOV  (PC)+,-(SP) 

.BYTE  97.,  1 

EMT  377 

BCC  . +6 

JSR  PC, ERR 


PUSH  DPB  ONTO  THE  STACK 

ENC'.'$S  MACRO  DIC,  DPB  SIZr.  =  l  WORD 

'^riAP  TO  THE  EXECUTIVE 

BRANCH  IF  DIRECTIVE  SUCCESSFUL 

OTHERWISE,  CALL  ROUTINE  "ERR" 


Local  Symbol  Definitions: 

None 
DSW  Return  Codes: 

IS. sue   --   Successful  completion. 

IE. ITS   —   Checkpointing  is  not  disabled  or  task  is  connected  to 
an  interrupt  vector. 

IL.ADP   —   Part  of  the  DPB  is  out  of  the  issuing  task's   address 
space . 

lE.SDP   —   DIC  or  DPB  size  is  invalid. 


Note : 


Because  this  directive  requires  onlv  a  1-word  DPB,  the  $S  form  of 
the  macro  is  recommended.  It  requires  less  space  and  executes 
with  the  same  speed  as  that  of  the  DIRS  macro. 
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5.3.26      Exit    If 

The  Exit  If  directivf?  instructs  the  system  to  terminate  the  execution 
of  the  issuing  task  if,  and  only  if,  an  indicat9d  event  flag  is  not 
set.  The  Executive  returns  control  to  the  issuing  task  if  the 
specified  event  flag  is  set.   °cc-  Notes  below. 

FORTRAN  Call : 

CALL  EXITIF  (efn[  .ids]  ) 

efn   =   Event  flag  number 

ids   =   Directive  status 

Macro  Cal 1 : 

EXIF$     efn 

efn   =   Event  flag  number 

Macro  Expansion: 

EXir$   52. 

.BYTE         53., 2  ;EXIFS    MACRO    DIC,     DPB    SI2E=2   WORDS 

.WORD         52.  ;EVENT    FLAG    NUMBER    52. 

Local    Symbol    Definitions: 

E.XFEF      —      Event    flag    number    (2) 
DSW   Return    Codes: 

IS. SET      --      Indicatec    EFN   set;       task    did    not    exit. 

lE.IEF  —  Invalid  event  flag  number  (EFN<1,  or  EFN>96,  if  group 
global  event  flags  exist  for  the  task's  group;  or 
5FN>64    if    not) . 

lE.ADP  --  P.Trt  of  the  DPB  is  out  of  the  issuing  task's  address 
s  pa  c  e  . 

lE.SDP      —     DIC   or    DPB   size    is    invalid. 
Motes : 

1.  The  Exit  If  directive  is  useful  in  avoiding  a  possible  race 
condition  that  can  occur  between  two  tasks  communicating  by 
means  of  the  Send  and  Receive  directives.  The  race  condition 
occurs  when  one  task  executes  a  Receive  directive  and  finds 
its  receive  queue  empty;  but  before  the  task  can  exit,  the 
other  task  sends  it  a  message.  The  message  is  lost  because 
the  Executive  flushed  the  receiver  task's  receive  queue  when 
!♦-  decided  to  exit.  This  condition  can  be  avoided  if  the 
sending  task  specifies  a  common  event  flag  in  the  Send 
directive  and  the  receiving  task  executes  an  Exit  If 
specifying  the  same  common  event  flag.  If  the  event  flag  is 
SvJt,  the  Exit  If  directive  will  return  control  to  the  issuing 
task,    signaling    that    something    has   been    sent. 


5-67 


DIRECTIVE  DESCRIPTIONS 

2.  A  FORTRAN  program  that  issues  the  Exit  If  call  must  first 
close  all  files  by  issuing  Close  calls.  See  the  IAS/RSX-11 
FORTRAN  IV  or  FORTRAN  IV-PLUS  User's  Guide  for  insFructions 
ori  how  to  ensure  tFat  such  files  are  closed  properly  If  the 
task  exits.  To  avoid  the  time  overhead  involved  in  the 
closing  and  reopening  of  files,  the  task  should  first  issue 
the  appropriate  test  or  clear  event  flag  directive.  If  the 
directive  status  word  indicates  that  the  flag  was  not  set, 
then  the  task  can  close  all  files  and  issue  the  call  to  Exit 
If. 

3.  On  Exit,  the  Executive  frees  task  resources.   In   particular, 
:he  Executive: 

Detaches  all  attached  devices 

Flust.co  the  AST  queue  and  despecifies  all  specified  ASTs 

Flushes  the  receive  and  receive-by-ref erence  queues 

Flushes  the  clock  queue   for   any   outstanding   »1ark   Time 
requests  for  the  task 

Closes  all  open  files  (files  open   for   write   access   are 
locked) 

Detaches  all  attached  regions,  except  in   the   case   of   a 
fixed  task 

Runs  down  the  task's  I/O 

Deaccesses  the  group  global  event   flags   for   the   task's 
group 

Disconnects  from  interrupts 

Flushes  all  outstanding  CLI  command  buffers  for  the  task 

Breaks  the  connection  with  any  offspring  tasks 

Returns  a  success  status  (EXSSUC)  to  any  parent  tasks 

Marks  for  deallocation  all  virtual  terminal  units  the  task 
has  created  (see  Section  5.2) 

Frees  the  task's  memory  if  the  exiting  task  was  not  fixed 

4.  If  the  task  exits,  the  Executive  declares  a  significant 
event . 
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5.3.27   Task  Exit  ($S  Form  Recommended) 

The   Task   Exit   directive   instructs   the   system   to   terminate   the 
execution  of  the  issuing  task. 

FORTRAN  Call : 

See  Note  5  below. 
Macro  Cal 1 : 

EXIT$S   [err] 

err   =   Error  routine  address 
Macro  Expansion: 


EXIT$S  ERR 

MOV  (PC)+,-(SP) 

.BYTE  51.,  1 

EMT  377 

JSR  PC, ERR 

Local  Symbol  Definitions: 

None 

DSW  Return  Codes: 


PUSH  DPB  ONTO  THE  STACK 

EXITSS    MACRO    DIC,     DPB    SIZE=1    WORD 

TRAP  TO  THE  EXECUTIVE 

CALL  ROUTINE  "ERR" 


lE.ADP 

lE.SDP 
Notes : 


Part  of  the  DPB  is  out  of  the  Issuing  task's   address 
space . 

DIC  or  DPB  size  Is  Invalid. 


1.  A  return  to  the  task  occurs  if,  and  only  if,  the  directive  is 
rejected.  Therefore,  no  Branch  on  Carry  Clear  instruction  is 
generated  If  an  error  routine  address  is  given,  since  the 
return  will  only  occur  with  carry  set. 

2.  Exit  causes  a  significant  event  to  be  declared. 

3.  On  Exit,  the  Executive  frees  task  resources.   In   particular, 
:he  Executive: 


Detaches  all  attached  devices 

Flushes  tiie  AST  queue  and  despecifles  all  specIfleJ  ASTs 

Flushes  the  receive  and  recel ve-by-ref erence  queues 

Flushes  the  clock  queue   for   any  outstanding   Mark   Time 
requests  for  the  task 

Closes  all  open  files  (files  open   for   write   access   are 
locked ) 
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Detaches  all  attached  regions,  except  In   the  case   of   a 
fixed  task,  where  no  detaching  occurs 

Runs  down  the  task's  I/O 

Deaccesses  the  group  global  event   flags   for   the   task's 
g  roup 

Disconnects  from  interrupts 

Flushes  all  outstanding  CLI  command  buffers  for  the  task 

Breaks  the  connection  with  any  offspring  tasks 

Returns  a  success  code  (EX$SUC)  to  any  parent  task 

Marks  for  deallocation  all  virtual  terminal  units  the  task 
has  created  (see  Section  5.2) 

Frees  the  task's  memory  if  the  exiting  task  was  not  fixed 

Because  this  directive  requires  only  a  1-word  DPB,  the  $S 
form  of  the  macro  is  recommended.  It  requires  less  space  and 
executes  with  the  same  speed  as  that  of  the  DIRS  macro. 

You  can  terminate  FORTRAN  tasks  with  the  STOP  statement  or 
with  CALL  EXIT.  CALL  EXIT  is  a  FORTRAN  OTS  routine  that 
closes  open  files  and  performs  other  cleanup  before  it  issues 
an  EXITSS  directive  for  an  EXSTS  directive  in  FORTRAN 
IV-PLUS).  FORTRAN  tasks  that  terminate  with  the  STOP 
statement  result  in  a  message  being  displayed  on  the  task's 
TI:.  This  message  includes  task  name  (as  it  appears  In  the 
Active  Task  List),  the  statement  causing  the  task  to  stop, 
and  an  optional  character  string  specified  in  the  STOP 
statement.  Tasks  that  terminate  with  CALL  EXIT  do  not 
display  a  termination  message.  For  .-xample,  a  FORTRAN  task 
containing  the  following  statement: 

20    STOP  'THIS  FORTRAN  TASK' 

exits  with  the  following  message  displayed  on  the  tasks  TI: 
(TT37  in  this  example) : 

TT37  —  STOP  THIS  FORTRAN  TASK 
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5. 3. 28   Exit  With  Status 

The  Exit  With  Status  directive  causes  the  issuing  task  to  exit, 
passing  a  16-bit  status  back  to  all  tasks  connected  (by  the  Spav«m, 
Connect,  or  Send,  Request  And  Connect  directive).  If  the  Issuing  task 
has  no  connected  tasks,  then  the  directive  simply  performs  a  Task 
Exit,  No  format  of  the  status  word  is  enforced  by  the  Executive; 
format  conventions  are  a  tjnction  of  the  cooperation  between  parent 
and  offspring  tasks.  However,  if  an  offspring  task  aborts  for  any 
reason,  a  status  of  L'XSSEV  is  returned  to  the  parent  task,  ThlB  value 
Is  interpreted  as  a  "severe  error"  by  Batch  processors.  Furthermore, 
if  a  task  performs  a  normal  exit  with  other  tasks  connected  to  it,  a 
status  of  EXSSUC  (successful  completion)  is  returned  to  all  connected 
tasks. 

FORTRAN  Call : 

CALL  EXST  (istat) 

istat    =   A  16-bit  quantity  to  be  returned  to  parent  task 

Macro  Cal 1 : 

EXST$        status 

status      =      A    16-blt    quantity   to    be    returned    to    parent    task 

Macro    Expansion: 

EXSTS  STWD 

.BYTE  29., 2  ;EXST$    MACRO    DIC,    DPB    SIZE'2    WORDS 

.WORD  STWD  ;VAL'JE    OF    STATUS    TO   BE    RETURNED 

Local    Symi-ol    Definitions: 

E.XSTS      —      Value    of    status    to    be    returned    (2) 

DSW   Return    Codes: 

No    status    is    returned    if    the   directive    is    successfully      completed 
since    the   directive    causes    the    issuing    task    to    exit. 

lE.ADP      --      Part   of    the    DPB    is   out   of    the    issuing    task's      addreps 
space . 

lE.SDP      —      DIC    ot    DPB    size    is    invalid. 
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Notes: 

1. 


The  execi'tive  does  the  following  to  free  a   task's   resoarc«« 
on  Exit: 

Detaches  all  attached  devices 

Flushes  the  AST  queue  and  despecifies  all  specified  ASTs 

Flushes  the  Receive  and  Rece 1 ve-by-ref erence  queues 

Flushes  the  clock  queue   for   any  outstanding   Mark   Time 
requests  for  the  task 

Closes  all  open  files  (files  open   for   write   access   are 
locked) 

Detaches  all  attached  regions  except   In   the   case   of   a 
fixed  task 

Runs  down  the  task's  I/O 

Deaccesses  the  gro'jp  global  event   flags   for   the   task's 
q  roup 

Disconnects  from  Interrupts 

Flushes  all  outstanding  CLI  command  buffers  for  the  task 

Breaks  the  connection  with  any  offspring  tasks 

Returns  the  specified  exit  status  to  any  parent  tasks 

Marks  for  deallocation  all  the  virtual  terminal  units  that 
the  task  has  ^^-eated 

Frees  the  task's  memory  If  the  exiting  task  was  not  fixed 

If  the  task   exits,   the   executive   declares   a   significant 
event . 
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5. 3. 29   Extend  Task 

The  Extend  Task  directive  instructs  the  system  to  modify  the  size  of 
the  issuing  task  by  a  positive  or  negative  increment  of  32-word 
blocks.  If  the  directive  does  not  specify  an  increment  value  or 
specifies  an  increment  value  of  zero,  the  Executive  makes  the  issuing 
task's  size  equal  to  its  installed  size.  The  issuing  task  must  be 
running  in  a  system-controlled  partition  and  cannot  have  any 
outstanding  I/O  when  it  issues  the  directive.  The  task  must  also  be 
checkpointable  to  Increase  its  size;  If  necessary,  the  Executive 
checkpoints  the  task,  and  then  returns  the  task  to  memory  with  its 
size  modified  as  directed. 

In  a  system  that  supports  the  memory  management  directives,  the 
Executive  does  not  change  any  current  mapping  assignments  If  the  task 
has  memory-resident  overlays.  However,  If  the  task  does  not  have 
memory-resident  overlays,  the  Executive  attempts  to  modify,  by  the 
specified  number  of  32-word  blocks,  the  mapping  of  the  task  to  its 
task  region. 

If  the  issuing  task  is  checkpointable  but  has  no  preallocated 
checkpoint  space  available,  a  positive  increment  may  require  dynamic 
memory  and  extra  space  in  a  checkpoint  file  sufficient  to  contain  the 
task . 

There  are  several  constraints  on  the  size  to  which  a  task  can  extend 
itself  using  the  Extend  directive: 

•  No  task  can  extend  itself  beyond  the  maximum  size  set  by  the 
MCR  command  SET  /MAXEXT  or  DCL  command  SET  EXTENSION  LIMIT  or 
the  size  of  the  partition  In  which  It  Is  running.  TSee  the 
RSX-llM/M-PLUS  MCR  Operations  Manual  or  the  RSX-llM/M-PLUS 
Command  Language  Manual . ) 

•  A  task  that  does  not  have  memory-resident  overlays  cannot 
extend  Itself  beyond  32K  minus  32  words. 

•  A  task  that  has  preallocated  checkpoint  space  in  its  task 
image  file  cannot  extend  itself  beyond  its  installed  size. 

•  A  task  that  has  memory-resident  overlays  cannot  reduce  its 
size  below  the  highest  window  In  the  task  partition. 

FORTRAN  Call : 

CALL  EXTTSK  ( ( inc]  [  ,  Id s]  ) 

Inc  =  A  positive  or  negative  number  equal  to  the  number  of 
32-word  blocks  by  which  the  task  size  Is  to  be  extended 
or  reduced 

Ids   =   Directive  status 
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Macro  Call : 

EXTK$         [inc] 
inc 


A  positive  or  negative  number  equal  to  the  number  of 
32-word  blocks  by  which  the  task  size  is  to  be  extended 
or    reduced 


Macro    Expansion: 

EXTK$         40 
.BYTE         89., 3 
.WORD         40 


.WORD         0 
Local    Symbol    Definitions: 

E.XTIN      —      Extend    increment    (2) 
DSW  Return   Codes: 

IS. sue      —      Successful    completion. 


EXTK$    MACRO    DIC,     DPB    SIZE=J    WORDS 
EXTEND    INCREMENT,     40(8)     BLOCKS     (IK 
WORDS) 
RESERVED   WORD 


IF.UPN 


IE. ITS 


lE.ALG 


Insufficient   dynamic   memory,    or    Insufficient    space    in 
a   checkpoint    file. 


The      issuing      task      is      not      running       In 
controllec     partition. 


system 


The  issuing  task  attempted  to  reduce  icii  size  to  less 
than  the  size  of  Its  task  header;  oi  the  task  tried 
to  increase  its  size  beyond  32K  words  or  Beyond  the 
maximum  set  by  the  MCR  SET  /MAXEXT  command  or  the  DCL 
SET  EXTENSION_LIMIT  command;  or  the  task  tried  to 
increase  its  size  to  the  extent  that  one  virtual 
address  window  would  overlap  another;  or  the  task 
has  memory-resident  overlays  and  it  attempted  to 
reduce  its  size  below  the  highest  window  mapped  to 
the  task  partition. 

IB.RSU   —  Other  tasks  are  attached  to  this  task  partition. 

lE.IOP   —  I/O  is  in  progress  for  this  task  partition. 

lE.CKP   —  The  issuing  task  is  not  checkpointable  and   specified 
a  positive  integer. 

IE. NSW   —  Attempt  to  extend  to  larger  than  installed  size  (when 
checkpoint  space  Is  allocated  in  the  task). 

lE.ADP   —   Part  of  the  DPB  is  out  of  the  issuing  task's   address 
space . 

lE.SDP   —   DIC  or  DPB  size  is  invalid. 
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5.3.30  Get  Command  for  Command  Interpreter 

The  Get  Command  for  Command  Interpreter  directive  instructs  the  system 
to  retrieve  a  command  buffer  for  a  Command  Line  Interpreter  (CLI)  task 
and  copy  It  to  a  buffer  in  the  task's  address  space.  Information 
about  the  issuing  terminal  can  also  be  returned  to  the  CLI  task. 

Only  CLI  tasks  can  issue  this  directive. 

FORTRAN  Call : 

CALL  GTCMCI  ( icbf , icbf 1 , [ I ibuf ] , [ i ibf 1 ] , ( i add r ]  , [ incp]  [ ,  ids]  ) 

Icbf   =  Name  of  a  byte  array  to  receive  the  command 

icbfl  =  Integer  containing  the  size  of  the  icbf  array  in  bytes 

iibuf  =  Name  of  an  integer  array  to  receive  the  optional 
information  buffer 

iibfl  =  Name  of  an  integer  containing  the  length  of  the 
optional  information  buffer.  If  you  specify  a  length 
shorter  than  the  information  buffer,  as  much 
information  as  will  fit  in  the  length  you  specified  Is 
returned . 

iaddr  =  Name  of  ?n  integer  that  contains  the  address  in  pool  of 
the  command  desired.  This  address  was  obtained  by  a 
previous  call  to  GTCMCI  with  GC.CND  specified. 

incp  =  Name  of  an  integer  containing  a  bit  mask  indicating  the 
action  to  take  if  there  is  no  command  queued: 

Octal 
Bit    Value  Definition 

GC.CCS    000    Return  with  carry  set  (default). 

GC.CEX   001     Force   CLI    to    exit    instead    of 

returning . 

GC.CST   002    Force   CLI    to    stop    instead    of 
returning . 

GC.CND    200    Copy  command  Into  buffer  but   do   not 
dequeue  it  from  the  list. 

You  must  specify  these   as   decimal   values   in   your 
FORTRAN  program. 

ids   =  Integer  to  receive  the  Directive  Status  Word 

Macro  Cal 1 : 

GCCI$  cbuf ,cbfl , [ ibuf] , [ibfl] , [addr] , [ncp] 

cbuf   =  Address  of  buffer  to  receive  command  string 
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cbfl   =  Length  of  buffer.   Maximum   buffer   size   is   91.    for 
RSX-llM  and  266.   for  RSX-llM-PLUS. 

ibuf   =  Address  of  buffer  to  receive  information  on  the  issuing 
terminal 

ibfl   =  Length  of  buffer  to  receive  information 

addr   =  Address  of  command. 

This  address  is  returned  in  G.CCCA  of  the  information 
buffer  if  GC.CND  is  specified  In  the  ncp  argument.  If 
this  argument  is  nonzero  then  only  the  command  with  the 
address  specified  by  this  drgument  is  copied  and/or 
dequeued.  Note  that  this  address  is  only  filled  in  If 
the  command  is  not  dequeued. 

ncp   =  Action  to  take  if  no  command  buffer  present: 

Octal 
Bit    Value  Definition 

GC.CCS    000    Return  with  carry  set  (default). 

GC.CEX   001    Force   CLI    -o    exit    instead    of 
returning . 

GC.CST    002    Force   CLI    to    stop    instead    of 
returning  . 

GC.CND    200    Copy  command  into  buffer  but   do   not 
dequeue  it  from  the  list. 


NOTE 

GC.CND  can  be  supplied  with  one  of 
tne  other  options,  for  example, 
GC.CNDIGC.CEX. 


Command  Buffer  Format: 

G.CCDV   --   ASCII  device  name  of  Issuing  terminal  (2) 

G.CCCT   --   Number  of  characters  (1) 

G.CCUN   --   Octal  unit  number  of  issuing  terminal  (1) 

G.CCCL   --   Number  of  characters  in  command  line  (2) 

G.CCFL   —   Flags  (1) 

The  values  returned  in  the  flag  byte,  G.CCFL,  are; 

Flag     Value        Definition 

GC.CNL  =     1     Null  command  line 
GC.CTE  -     2     Prompt  from  a  task  exit 
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G.CCTC      —      Terminator    (1) 

G.CCBF      —      Command    text    In    ASCII     (80    byte      on      RSX-llM      systems, 
256  bytes  on   RSX-llM-PLUS   systemB) 

Information    Buffer    Format: 

The    format    of    the    information    buffer       in      the      CLI      address      task 
space    is: 

G.CCW2  —  U.CW2   of    issuing    terminal     (2) 

G.CCPT  —  Name   of    parent    task    (if    anyi     (4) 

G.CCOA  —  Address   of    offspring    control    block    from    parent    (2) 

G.CCPU  —  Login    UIC   of    issuing    terminal     (2) 

G.CCCU  —  Current    UIC   of    issuing    terminal     (2) 

G.CCCA  --  Address   of    command,    if    not   dequeued     (2) 

Macro    expansio.  t 

CBUF,CBFL, IBUF, IBFL, ADDR , NCP 

;DIC=    127.,     DPB    RTZE=7    WORDS 

;ACTION  TO  TAKE  IF  NO  COMMAND  QUEUED 

ADDRESS  OF  COMMAND 
COMMAND  BUFFER  ADDRESS 
COMMAND  BUFFER  LENGTH 
INFORMATION  BUFFER  ADDRESS 
INFORMATION  BUFFER  LENGTH 

Local  Symbol  Definitions: 

G.CCNC  --   Action  if  no  command  queued  (2) 

G.CCAD  —   Address  of  command  to  be  returned  (2) 

G.CCBA  —   Address  of  command  buffer  (2) 

G.CCBL  —   Length  of  task's  command  buffer  (2) 

G.CCIA  —   Address  of  optional  information  buffer  (2) 

G.CCIL  —   Length  of  optional  information  buffer  (2) 

DSW  Return  Codes: 

IE. AST  - 


GCCI$ 

CBUF,C 

.BYTE 

127. ,7 

.BYTE 

NL? 

.BYTE 

0 

.WORD 

ADDR 

.WORD 

CBUF 

.WORD 

CBFL 

.WORD 

IBUF 

.WORD 

IBFL 

The   stop-on-no-command   option   w<-*s   set 
directive  was  issued  from  AST  state. 


and    the 


lE.PRI   —   Task  is  not  a  CLI. 

lE.RSU  --  The  Issuing  task  has  a  group  global  context  active 
and  next  command  to  be  received  would  have  caused  the 
task's  protection  group  to  have  changed. 
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IE, ITS  —  No  command  was  queued  for  the  CLI  and  the  directive 
was  issued  with  the  return-wi th-car ry-set  option. 

IS.CLR  --  Returned  with  carry  clear  when  the  CLI  was  unstopped 
due  to  command  arrival,  after  having  been  stopped  by 
a  ecus  with  the  stop-on-no-command-opt  ion  set. 

lE.ADP  —  DPB,  send  buffer  or  information  buffer  was  outside 
the  task's  address  space,  or  the  information  buffer 
was  shorter  than  nine  bytes. 

lE.SDP   --   Die  and  DPB  size  is  invalid. 

Notes: 

1.  The  number  of  characters  returned  (G.CCCT)  could  be  less  than 
the  number  of  characters  In  the  command  (G.CCCL)  if  the 
length  of  the  command  buffer  in  the  task,  as  specified  by 
cbfl  argument,  is  smaller  than  the  actual  command  line.  If 
there  Is  sufficient  room,  a  carriage  return  Is  placed  at  the 
end  of  the  command  line  returned  at  G.CCBF  in  the  command 
buffer  inside  the  task  to  ease  parsing. 

2.  If  a  command  Is  successfully  returned,  the  protection  and 
default  UICs  for  the  issuing  task  are  changed  by  this 
directive  to  match  the  UICs  of  the  originating  terminal. 
These  UICs  are  returned  In  words  G.CCPU  and  G.CCCU  of  the 
oDtlonal  information  buffer. 
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5.3.31   Get  Conmand  Interpreter  Information 

The  Get  Command  Interpreter  Information  directive  Instructs  the  system 
to  fill  a  buffer  with  information  about  a  specified  CLI  or  the  CLI 
associated  with  a  given  terminal.  A  task  must  be  privileged  In  order 
to  Issue  this  di  ectlve  for  any  terminal  other  than  Its  own  TI : ,  or  a 
CLI  to  which  Its  TI:   is  not  set. 

FORTRAN  Call : 

CALL  GETCII  ( Ibuf  ,  1 bf 1 , i  ic 1  I ]  , (  idev 1  , ( I un 1 1 M , 1 d s)  ) 

Ibuf   »   Name  of  an  Integer  array  to  receive  the  CLI 
Information 

IbCl   »   Length  in  bytes  of  the  Integer  art  \.  receive  the 

CLI  information 

icll  "      Name  of  a  two-word  array  element  containing  the 
Radix-50  name  of  the  CLI 

idev   =■   Name  of  an  Integer  containing  the  ASCII  name  of 
terminal  (default  «  TI:) 

lunlt  =   Name  of  an  Integer  containing  the  Octal  jnlt  numbtT 
of  terminal 

Ids    =   Directive  status 

MACRO  Cal 1 : 

GCIIS    buf ,buf 1 , fcl U , rdev,unlt] 

buf         =      Address   of   buffer    to    receive    information 

bufl      =      Length   of    information   buffer 

cl i         =      Name    in    Radix-5C   of    the    CLI    that    information    is 
requested    on 

dev        =      ASCII    name    of    terminal    whose    f^LI    should    be    used 
(default    '   TI: ) 

unit      =      Octal    unit    number    of    tei-^inal 

Information    Buffer    Format: 

G.CICL      --     Name   of    CLI 

G.CICS      —      Bit    settings    in    the    CLI    scatus    wo  r J  : 

Bit  Value  Definition 

CP.NUL=  1  Pass    empty    command    lines    to    CLI. 

CP.MSG"  2  CLI   wants    system   messages. 

CP.LGO=  4  CLI   wants   commands    from    logged-off 

terminals. 
CP.DS8=>  1(5        CLI    is    disabled.       (Note      that      MCR 

does    not    check    this   bit.) 
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Nt 

Value 

CP.PRV=» 

20 

CP.SGL- 

40 

CP.NIO- 

100 

DIRECTIVE  DESCRIPTIONS 

Definition 

User  must  be  privileged  to  set 
terminal  to  this  CLI. 
Don't  handle  continuations. 
Always  set  on  RSX-llM  systems. 
100  MCR...,  HEL,  BYE  do  no  I/O  to 
terminal;  HEL,  BYE  also  do  not 
set  CLI,  and  so  forth. 

CP.RST"  200  Restricted  access;  only  this  CLI 
task  can  set  a  terminal  to  this 
CLI. 

CP.EXT=  400  Pass  task  exit  prompt  requests  to 
CLI. 

G.CITK  —  Name  of  task  serving  as  CLI 

G.CIW2  —  Terminal's  U.CW2 

G.CIPU  —  Terminal's  protection  UIC 

G.CICU  —  Terminal's  current  UIC 

G.CIDP   —  CLI  default  prompt  string  (16-byte  block.   First  byte 
is  length  of  string.) 

Macro  Expansion: 

GCII$  buf ,buf 1 ,cl i ,dev,unit 

.BYTE  173,7  ;DIC  tc  be  supplied.   DPB  SIZE=5 

.WORD  but  ;ADDRESS  OF  BUFFER 

.WORD  bufl  ; LENGTH  OF  BUFFER 

.RAD50  /cli/  <?  ;RAD50  NAME  OF  CLI 

.ASCII  /dev/  ;ASCII  NAME  OF  TERMINAL 

.WORD  unit  /TERMINAL  UNIT  NUMBER 

DSW  Returns: 

IE. MAP   —   Boch  a  terminal  and  a  CLI  were  specified. 

IE. INS   —  Specified  CLI  does  not  exist. 

lE.IDU   —  Specified  device  was   not   a   terminal   or   does   not 
ex  ist . 

lE.PRI   —  Nonpr ivileged  task  attempted  to  get  information  on   a 
CLi  other  than  it's  own. 

lE.ADP   —   Part  of  the  DPB  or  buffer   was   out   of   the   issuing 
task's  address  space. 

lE.SDP   —  Die  or  DPB  size  is  invalid. 

Notes  : 

1.  If  the  buffer  is  not  long  enough  to  contain  all  the 
information,  the  data  that  does  not  fit  will  not  be  supplied. 
No  indication  of  this  is  returned  to  the  issuing  task.  The 
buffer  is  filled  from  left  to  right. 

2.  You  may  not  specify  both  a  CLI  and  a  terminal.  If  the  cli 
argument  is  present,  the  dev  and  unit  arguments  must  be  zero. 
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5.3.32     Get    LUN    Information 

The  Get  LUN  Information  directive  instructs  the  system  to  fill  a 
6-word  buffer  with  information  about  a  physical  device  unit  to  which  a 
LUN  is  assigned.  If  requests  to  the  physical  device  unit  have  been 
redirected  to  another  unit,  the  information  returned  will  describe  the 
effective    assignment. 

FORTRAN   Call : 

CALL   GETLUN     ( 1 un ,dat [ , ids ]  ) 

lun      =      Logical    unit    number 

dat      =      A    6-word    integer    array    to    receive    LUN    information 

ids      =      Directive    status 

Macro    Call : 

GLUN$         lun    buf 

lun      =      Logical    unit    number 

b    I      =      Address      of      6-word      buffer    that      will      receive    the    LUN 
information 

Buffer    Format: 

Word      0      --      Name   of   assigned    device 

Word  _  --  Unit  number  of  assigned  device  and  flags  byte  (flags 
byte  equals  200  if  the  device  driver  is  resident  or 
0    if    the   driver    is    not    loaded) 

Word      2      --      First   device   characteristics   word: 

Bit    0      --      Record-oriented    device 
(DV.REC, l=yes) [FD.REC] ^ 

Bit    1      --      Carriage-control    device 
(DV.CCL, l=yes) [FD.CCL] 

Bit    2      --      Terminal    device    (DV.TTY, l=yes) [FD. TTY] 

Bit    3      --      Directory    (file-structured) 

device    (DV. DIR, l=yes) [FD. DIR] 

Bit  4   --   Single  directory  device 
(DV.SDI, l=yes) [FD.SDI] 

Bit  5   --   Sequential  device  (DV. SQD, l=yes) [FD. SQD] 

Bit  6   —  Mass  storage  device  (DV.MSD, l=yes) 

Bit  7   —   User-mode  diagnostics  supported  (DV. UMD, l=yes) 


1.  Bits  with  associated  symbols  have  the  symbols  shown  in  square 
brackets.  These  symbols  can  be  defined  for  use  by  a  task  by  means  of 
the  FCSBT$  macro.   See  the  IAS/RSX-11  I/O  Operations  Reference  Manual . 
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Bit  8   —   Device  supports   extended   22-bit   UNIBUS 
controller  (DV. EXT, l=yes) 

Bit  9   —  Unit  software  write-locked  (DV. SWL, l=ye3) 

Bit  10  --  Input  spooled  device  (DV. ISP, l=yes) 

Bit  11  —  Output  spooled  device  (DV. OSP, l=yes) 

Bit  12  —  Pseudo  device  (DV. PSE, I=yes) 

Bit  13  --   Device   mountable   as   a   communications 
channel  (DV.COM ,  l=yes) 

Bit  14  —   Device  mountable   as   a   Files-11   device 
(DV.Fll, l»yes) 

Bit  15  —   Device  mountable  (DV.MNT, l=yes) 

Word   3   —  Second  device  characteristics  word 

Word  4  —  Third  device  characteristics  word  (words  3  and  4  are 
device  driver  specific) 

Word  5  —  Fourth  device  characteristics  word  (normally 
buf'fer-size  as  specified  in  the  MCR  or  DCL  SET/BUFF 
command) 

Macro  Expansion: 

GLUNS  7,LUNBUF 

.BYTE  5,3  ;GLUN$  MACRO  DIC,  DPS  SIZE=3  WORDS 

.WORD  7  ; LOGICAL  UNIT  NUMBER  7 

•  WORD  LUNBUF  .-ADDRESS  OF  6-WORD  BUFFER 

Local  Symbol  Definitions: 

G.LULU   —   Logical  unit  number  (2) 

G.LUBA   --   Buffer  address  (2) 

The  following  offsets  are  assigned  relative  to  the  start   of   the   LUN 
information  buffer: 

G.LUNA  —  Device  name  (2) 

G.LUNU  —  Device  unit  number  (1) 

G.LUFB  --  Flags  byte  (1) 

G . LUCW  —  Four  device  characteristics  words  (8) 

DSW  Return  Codes: 

IS. sue  —  Successful  completion. 

lE.ULN  --  Unassigned  LUN. 

lE.ILU  —  Invalid  logical  unit  number. 

lE.ADP   —   Part  of  the  DPB  or   buffer   is   out   of   the   issuing 
task's  address  space. 

lE.SDP   —   DIC  or  DPB  size  is  invalid. 
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Note; 

If  a  spooled  device  is  found  in  the  redirection  chain  and  the 
issuing  task  is  not  the  despooler,  the  LUN  information  returned 
by  the  Executive  is  as  follows: 

Word   0   —  Name  of  assigned  (spooled)  device 

Word  1  --  Unit  number  of  assigned  spooled  device  and  flaqs 
byte  ^ 

Word  2  —  Logical  OR  of  the  first  device  characteristics 
word  for  the  iritermed  iate  device  and  the  output 
spool  bit  (spooled  device  first  characteristics 
word,  bit  11) 

Word   3   —  Spooled  device  fourth  device  characteristics  word 

Word   4   —   Not  defined 

Word   5   —   Intermediate  device  standard  device  buffer  size 
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5.3.33   Get  MCR  Conmand  Line 

The  Get  MCR  Command  Line  directive  instructs  the  system  to  transfer  an 
80-byte  command  line  to  the  Issuing  task. 

When  a  task  is  installed  with  a  task   name   of  "...tsk"   or   "tskTn", 

where   "tsk"   consists   of   three   alphanumeric  characters  and  n  is  an 

octal  terminal  number,  the  MCR  dispatcher  requests  the  task's 
execution  when  a  user  issues  the  command 

>tsk  command-line 

from  terminal  number  n.  A  task  Invoked  in  this  manner  must  execute  a 
call  to  Get  MCR  Command  Line,  which  results  in  the  entire  "command 
line"  following  the  prompt  being  placed  into  an  80-byte  command  line 
buffer.  (The  MCR  dispatcher  is  described  In  the  RSX-1 IM/M-PLUS  MCR 
Operations  Manual  . ) 

FORTRAN  Call  : 

CALL  GETMCR  (buf[,lds]) 

buf   =   An  80-byt3  array  to  receive  command  line 

Ids   =   Directive  status 

Macro  Cal  1  : 

GMCRS 

Macro  Expansion: 

GMCRS 

.BYTE    127., 41.  ;GMCR$  MACRO  DIG,  DPB  SIZE  =  41.   WORDS 

.BLKW    40.  ;80.   CHARACTER  MCR  COMMAND  LINE  BUFFER 

Local  Symbol  Definitions: 

G.MCRB   --   MCR  line  buffer  (80) 

DSW  Return  Codes: 

+n  --  Successful  completion;  n  is  the  number  of  data  bytes 
transferred  (excluding  the  termination  character). 
The  termination  character  Is,  however,  in  the  buffer. 

IE. AST  —  No  MCR  command  line  exists  for  the  issuing  task; 
that  is,  the  task  was  not  requested  by  a  command  line 
as  follows: 

>tsk  command-string 

or  the  task  has  already  issued  the   Get   MCR   Command 
Line  d  i  reot  i ve . 

lE.ADP  —  Part  of  the  DPB  is  out  of  the  issuing  task's  address 
space . 

lE.SDP   —   Die  or  DPB  size  is  invalid. 
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Notes : 


1.  The  GMCRSS  form  of  the  macro  Is  not  supplied,  since  the  DPB 
receives  the  actual  command  line. 

2.  The  system  processes  all  lines  to: 

•  Convert  tabs  to  a  single  space 

•  Convert  multiple  spaces  to  a  slnqle  space 

•  Convert  lowercaae  to  uppercase 

•  Remove  all  trailing  blanks 

The  terminator  (<CR>  or  <ESC>)  Is  the  last  character   in   the 
line. 

3.  On  RSX-llM-PLUS  syattfms,  if  ^he  character  before  the 
terminator  is  a  hyphen,  there  is  at  least  one  continuation 
line   present.    Therefore,   you  must   issue   another   GMCR$ 

,   directive  to  obtain  the  rest  of  the  coumand  3lne. 
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5.3.34   Get  Mapping  Context 

The  Get  Mapping  Context  directive  causes  the  Executive  to  return  a 
description  of  the  current  window-to-req ion  mapping  assignments.  The 
returned  description  Is  In  a  form  that  enables  the  user  to  restore  the 
mapping  context  through  a  series  of  Create  Address  Window  directives 
(see  Section  5.3.11).  The  macro  argument  specifies  the  address  of  a 
vector  that  contains  one  Window  Definition  Block  (WDB)  for  each  window 
block  allocated  in  the  task's  header,  plus  a  terminator  word. 

For  each  window  block  in  the  •■ask's  header,  the  Executive  sets  up  a 
WDB  in  the  vector  as  follow? 

1.  If  the  window  block  is  unused  (that  is,  if  It  does  not 
correspond  to  an  existing  address  window),  the  Executive  does 
not  record  any  information  about  that  block  in  a  WDB. 
Instead,  the  Executive  uses  the  WDB  to  record  information 
about  the  first  block  encountered  that  corresponds  to  an 
existing  window.  In  this  way,  unused  window  blocks  are 
ignored  in  the  mapping  context  description  returned  by  the 
Execut Ive . 

2.  If  a  window  block  describes  an  existing  unmapped  address 
window,  the  Executive  fills  in  the  offsets  W.NID,  W.NAPH, 
W.NBAS,  and  W.NSIZ  with  information  sufficient  to  re-create 
the  window.   The  window  status  word  W.NSTS  is  cleared. 

3.  If  a  window  block  describes  an  existing  mapped  window,  the 
Executive  fills  in  the  offsets  W.NAPR,  W.NBAS,  W.NSIZ, 
W.NRID,  W.NOFF,  W.NLEN,  and  W.NSTS  with  information 
sufficient  to  create  and  map  the  address  window.  WS.MAP  Is 
set  in  the  status  word  (W.NSTS)  and,  if  the  window  is  mapped 
with  write  access,  the  bit  WS.WRT  Is  set  as  well. 

Note  that  in  no  case  does  the  Executive  modify  W.NSRB. 

The  terminator  word,  wh'.ch  foPows  the  last  WDB  filled  in,  is  a  word 
equal  to  the  negative  of  the  total  number  of  window  blocks  in  the 
task's  header.  It  Is  thereby  possible  to  issue  a  TST  or  TSTB 
inbtructlon  to  detect  the  last  WDB  used  in  the  vector.  The 
terminating  word  can  also  be  used  to  determine  the  number  ol!  window 
blocks  built  into  the  task's  header. 

When  Create  Address  Window  directives  are  used  to  reatore  the  mapping 
context,  there  is  no  guarantee  that  the  same  address  window  IDs  will 
be  used.  The  user  must  therefore  be  careful  to  use  the  latest  window 
IDs  returned  from  the  Create  Address  Window  directives. 

FORTRAN  Call : 

CALL  GMCX  (imcx[  ,ids] ) 

imcx  =  An  integer  array  to  receive  the  mapping  context.  The 
size  of  the  array  is  8*n-t-l  where  n  is  ^he  nunber  of 
window  blocks  in  the  task's  header.  The  maximum  slie 
Is  S'S-t-lse!"  words  on  RSX-llM  systems.  The  maximum 
size  is  8*24  +  l'«193  on  R3X-11M-PLU5  systems. 

ids   =   Directive  status. 
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Macro  Call : 

GMCX$    wvec 

wvec  =  The  address  of  a  vector  of  n  Window  Definition  Blocks, 
followed  by  a  terminator  word;  n  is  the  number  of 
window  blocks  in  the  tasl.'s  header. 

Macro  Expansion: 

GMCX$    VECADR 

.BYTE    .113.,  2  ;GMCX$  MACRO  DIG,  DPB  SIZE  =  2  WORDS 

.WORD    VECADR  ;WDB  VECTOR  ADDRESS 

Window  Definition  Block  Parsmeters: 

Input  parameters: 

None 

Output  parameters: 

Array       Offset 
Element 

iwdb(l)     W.NID   —   ID  of  address  window 
bits  0-7 

iwdb(l)      W.NAPR   —   Base  APR  of  the  window 
bits  8-15 

iwdb(2)      W.NBAS   —   Base  virtual  address  of  the  window 

iwdb(3)      W.NSIZ   —   Size,  in  32-word  blocks,  of  the  window 

iwdb(4)      W.NRID   --   ID  of   the  mapped  region,  or  no  change  if 

the  window  is  I'nmapped 

iwdb{5)      W.NOFF   —   Offset,  in  32-word  blocks,  from  the  start 

of  the  region  at  which  mapping  begins,  or 
no  change  if  the  window  is  unmapped 

iwdb(6)      W.NLEN   —   Length,  in  32-word  blocks,   of   the   area 

currently  mapped  within  the  region,  or  no 
change  if  the  window  is  unmapped 

iwdb(7)      W.NSTS   —   Bit  settings^  in  the  window  status   word 

(all  0  if  the  window  is  not  mapped): 

Bit  Definition 

WS.MAP      1  if  the  window  is  mapped 

WS.WRT  1  if  the  window  is  mapped 
with  write  access 

WS.SIS  1  if  the  window  is  mapped  in 
supervisor-mode  instruction 
space 


1.  If  you   are   a   FORTRAN   programmer,   refer   to   Section   3.5.2   to 
determine  the  bit  values  represented  by  the  symbolic  names  described. 
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Bit  Definition 

WS.UDS  1  If  the  window  Is  mapped  In 
user-mode  data  space 

WS.NBP  1  if  the  window  was  created 
with  cache  bypass  disabled 
(on  multiprocessor  systems 
only) 

WS.RCX  1  if  cache  bypass  has  been 
enabled  for  the  current 
mappln-g  of  the  window  (on 
multiprocessor  systems  only) 

Note  that  the  length  mapped  (W.NLEN)  can  be  less  than  the  size  of 
the  window  (W.NSIZ)  if  the  area  from  W.NOFF  to  tho  end  of  the 
partition  is  smaller  than  the  window  size. 

Local  Symbol  Definitions: 

G.MCVA   —  Address  of  the  vector  (wver)   containing   the   window 
definition  blocks  and  terminator  word  (2) 

DSW  Return  Codes: 

IS. sue   —   Successful  completion. 

lE.ADP   --  Address  check  of  the  DPB  or  the  vector  (wvec)  failed. 

lE.SDP   —   DIG  or  DPB  size  is  invalid. 
Note: 

Due  to  the  use  of  the  WS.RCX  to  indicate  cache-bypass  state,  you 
may  need  to  do  additional  manipulation  of  the  WDB  before  you 
issue  a  CRAW$  or  MAPS  directive.  (On  multiprocessor  systems 
only.) 
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5.3.35  Get  Partition  Parameters 

The  Get  Partition  Parameters  directive  Instructs  the  system  to  fill  an 
indicated  3-word  buffer  with  partition  parameters.  If  a  partition  Is 
not  specified,  the  partition  of  the  issuing  task  is  assumed. 

FORTRAN  Call : 

CALL  GETPAR  ( [ pr t ] , buf ( , Ids) ) 

prt   =   Partition  name 

buf   =  A  3-word  integer  array  to  receive  partition  parameters 

ids   =   Directive  status 
Macro  Cal 1  : 

GPRT$         [prt], buf 

prt      =      Partition    name 

buf      =      Address  of   a    3-word    buffer 
Buffer    Format: 

Word  0  --  Partition  physical  base  address  expressed  as  a 
multiple  of  32  words  (partitions  are  always  aligned 
on  32-word  boundaries).  Therefore,  a  partition 
starting  at  40000(8)  will  have  400(8)  returned  in 
this   word. 

Word      1      --      Partition    size    expressed    as   a   multiple   of    32   words. 

Word  2  --  Partition  flags  word.  This  word  is  returned  equal 
to  0  to  indicate  a  system-controlled  partition,  or 
equal    to    1    to    Indicate   a    user-controlled    partition. 

Macro    Expansion: 

GPRTS  ALPHA, DATBUF 

.BYTE  65., 4  ;GPRT$    QIC,    DPB    SIZE=4    WORDS 

.RAD50  /ALPHA/  ; PARTITION    "ALPHA" 

.WORD  DATBUF  /ADDRESS    OF    3-WORD    BUFFER 

Local    Symbol    Definitions: 

G.PRPN      --      Partition    name    (4) 

G.PRBA      —      Buffer    address    (2) 
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The  following  offsets  are   assigned   relative   to   the   start   of   the 
partition  parameters  buffer: 

G.PRPB   —   Partition   physical   base   address   expressed   as   an 
absolute  32-word  block  number  (2) 

G.PRPS   —   Partition  size  expressed  as   a   multiple   of   3?-word 
blocks  (2) 

G.PRFW   —   Partition  flags  word  (2) 

DSW  Return  Codes: 

Successfjl  completion  is  indicated  by  a  cleared  Carry  bit,  and 
the  starting  address  of  the  partition  is  returned  in  the  DSW.  In 
unmapped  systems,  the  address  is  physical.  In  mapped  systems, 
the  returned  address  is  virtual  and  is  always  zero  if  it  is  not 
the  task  partition.  Unsuccessful  completion  is  indicated  by  a 
set  Carry  bit  and  one  of  the  following  codes  in  the  DSW: 

IE. INS   —   Specified  partition  not  in  system. 

lE.ADP   --   Part  of  the  DPB  or  buffer  is  out   of   the   issuing 
task's  address  space. 


Notes  i 


lE.SDP   —   Die  or  DPB  size  is  invalid. 


For  Executives  that  support  the  memory  management  directives, 
a  variation  of  this  directive  exists  called  Get  Region 
Parameters  (see  Section  5.3.36).  When  the  first  word  of  the 
2-word  partition  name  is  0,  the  Executive  interprets  the 
second  word  of  the  partition  name  as  a  region  ID.  If  the 
2-word  name  is  0,0,  it  refers  to  the  task  region  of  the 
issuing  task. 

Omission  of  the  partition-name  argument  returns  parameters 
for  the  issuing  task's  unnamed  subpartition,  not  for  the 
system-controlled  partition. 
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5.3.36   Get  Region  Parameters 

The  Get  Region  Parameters  (Jirective  instructs  the  Executive  to  fill  an 
indicated  3-word  buffer  with  region  parameters.  If  a  region  is  not 
specified,  the  task  region  of  the  issuing  task  is  assumed. 

This  directive  is  a  variation  of  the  Get  Partition  Parameters 
directive  (see  Section  5.3.35)  for  Executives  that  support  the  memory 
management  directives. 

FORTRAN  Call : 

CALL  GETREG  (  [ r id ]  , buf [ , id s]  ) 

rid   =   Region  id 

buf      =      A    3-word    integer    array    to    receive    region    parameters 

ids      =      Directive    status 
Macro    Cal 1 : 
GREG$ 

rid      = 

buf      = 
Buffer    Format 


[ridl ,buf 
Region    ID 
Address   of    a    3-word    buffer 


Word      0      —      Region    base    address   expressed    as    a      multiple  of      32 

words         (regions        are      always      aligned      on  32-word 

boundaries).      Thus,    a      region      starting      at  1000(8) 
will    have    10(8)    returned    in    this    word. 

Word       1       --      Region    size    expressed    as    a    multiple    of    32   words. 

Word  2  --  Region  flags  word.  This  word  is  returned  equal  to  0 
if  the  region  resides  in  a  system-controlled 
partition,  or  equal  to  1  if  the  region  resides  in  a 
user-controlled    partition. 

Macro    Expansion: 


GREG$  RID,DATBUF 

.BYTE         65. ,4 
.WORD         0 


.WORD 
.WORD 


RID 
DAT3UF 


GREGS    MACRO    DIC,     DPS    SIZE'4    WORDS 

WORD   THAT    DISTINGUISHES    GREGS 

FROM    GPRT$ 

REGION    ID 

ADDRESS    OF    3-WORD   BUFFER 


Local    Symbol    Definitions: 

G.RGID      --      Region    ID    (2) 
G.RGBA      --      Buffer    address 
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The    following    offsets   are    assigned    relative    to    the    start   of    the    region 
parameters    buffer: 

G.RGRB      --      Region   base    address    expressed    as    an   absolute      32-word 
block   number    (2) 

G.RGRS      --      Region      size      expressed      as      ^      multiple      of      32-word 
blocks    (2) 

G. RGFW      --      Region    flags    word    (2) 

DSW    Return    Codes: 

Successful  completion  Is  indicated  by  carry  clear,  and  the 
starting  address  of  the  region  Is  returned  in  the  DSW.  In 
unmapped  systems,  the  returned  address  is  physical.  In  mapped 
systems,  thp  returned  address  is  virtual  and  is  always  zero  if  It 
Is  not  the  task  region.  Unsuccessful  completion  is  Indicated  by 
carry   set    and    one   of    the    following    codes    in    the    DSW: 

lE.NVR      --      Invalid    region    ID. 

lE.ADP      --      Part    of    the    DPB    or    buffer    is    out      of      the       Issuing 
task's   address    space. 

lE.SDP      --      Die    or    DPB    size    is    Invalid. 
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5.3.J7   Get  Sense  Switches  (SS  For*  Recoamended) 

The  Get  Sense  Switches  directive  instructd  the  system  to  obtain  the 
contents  of  the  console  switch  register  and  store  it  in  the  issuing 
task's  Directive  .Status  word. 

FORTRAN  Call  : 

CALL  READSW  (  l.-jw) 

Isw   .   Integer  to  receive  the  console  .Twitch  settings 

The  following  FORTRAN  call  allows  a  program  to  read  the  state  of  a 
single  switch: 

CALL  SSWTCH      (ibt,ist) 

ibt   X   The  switch,  to  be  tested  (0  to  15) 

ist   ■   Test  results  where: 

1  •   switch  on 

2  -   switch  off 
Macro  Cal 1 : 

GSSW$S   (errl 

err   =   Error  routine  address 

Macro  Expansion: 

GSSWSS  ERR 

MOV  (PC)+,-(SP)  ;PUSH    DPB    ONTO    THi:    STACK 

.BYTE  125.,  1  ;GSSW$S    MACRO    DIC,     DPB    SIZE=1    WORD 

EMT  377  ;TRAP   ?0   THE    EXECUTIVE 

^CC  .+6  .BRANCH     IF    DIRECTIVE    SUCCESSFUL 

JSR  PC,  ERR  .-OTHERWISE,    CALL    ROUTINE    "ERR" 

Local    Symbol    Definitions: 

None 

DSW  Return  Codes: 

Successful  completion   is   indicated   by   carry   clear,   and  the 

contents   of  th,  console  switch  register  are  returned  in  the  DSW. 

Unsuccessful  completion  is  indicated  by  carry  set  and  one  of  the 
following  codes  in  the  DSW: 


lE.ADP   - 

lE.SDP      --      DIC    or    DPB    size    is    Inv/alid 


Part      of       the         DPB       is      out      of       the    Issuing       ta.sk's 
address    space. 
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1.  Because  this  directive  requires  only  a  1-word  DPB,  the  $S 
form  of  the  macro  is  recommended.  It  requires  less  spcice  and 
executes  with  the  same  speed  as  that  of  the  DIR$  macro. 

2.  On  multiprocessor  systems,  the  value  returned  is  that  of  the 
virtual  switch  register  maintained  by  the  MCR  SWR  command. 
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5.3.38  Get  Time  Parameters 

The  Get  Time  Parameters  directive  instructs  the  system  to  fill  an 
indicated  8-word  buffer  with  the  current  time  parameters.  All  time 
parameters  are  delivered  as  binary  numbers.  The  value  ranges  (in 
decimal)  are  shown  in  the  table  below. 

FORTRAN  Call : 

CALL  GETTIM  (ibfp( ,ids] ) 

ibfp  =  An  8-word  integer  array 
Macro  Call : 

GTIM$    buf 

buf      =      Address   of    8-word    buffer 
3uffer    Format: 

Woid      0      —  Year    (since    1900) 

Word      \      —  Month    (1-12) 

Word      2      --  Day    (1  -31) 

Word      3      —  Hcur    (U-23) 

Word      4       --  Minute    (0-59) 

Word      5      —  Second    (0-59) 

Word      6      —     Tick   of   second    (depends   on    the    frequency  of    the 
clock) 

Word      7      —     Ticks    per    second    (depends   on    the    frequency  of    the 
clock) 

Macro    Expansion: 

GTIM$  DATBUF 

.BYTE         61,, 2  ;GTIM$    DIC,     DPS    SIZE=2   WORDS 

.WORD  DATBUF  ;ADDRESS    OF    8. -WORD    BUFFER 

Local    Symbol    Definitions: 

G.TIBA      —      Buffer    address    (2) 
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The  following  offsets  are  assigned  relative  to  the  start  of   the   time 
parameters  buffer: 

G.TIYR  --  Year  (2) 

G.TIMO  --  Month  (2) 

G.TIDA  --  Day  (2) 

G.TIHR  --  Hour  (2) 

G.TIMI  --  Minute  (2) 

G.TISC  —  Second  (2) 

G.TICT  —  Clock  Tick  of  Second  (2) 

G.TICP  --  Clock  Ticks  per  Second  (2) 

DSW  Return  Codes: 

IS. sue  —  Successful  completion. 

lE.ADP   —   Part   of   the  DPB   or   buffer  Is   out  of  the  issuing 
task's  address  space. 

lE.SDP   —   Die  or  DPB  size  is  invalid. 

Note: 

The  format  of  the  time  buffer  is   compatible   with   that   of   the 
buffers  used  with  the  Set  System  Time  directive. 
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5.3.39   Get  Task  Parameters 

The  Get  Task  Parameters  directive  instructs   the   system   to   fill   an 
indicated  16-word  buffer  with  parameters  relating  to  the  issuing  task. 

FORTRAN  Call: 

CALL  GETTSK  (buf[,lds)) 

buf   =   A  16-word  integer  array  to  receive  the  task  parameters 
ids   =   Directive  status 
Macro  Call  : 

GTSKO   buf 

buf      =      Address   of    a    16-word    buffer 

Buffer    Format : 

Word      0      —  Issuing    task's    name    in    Radix-50    (first    half) 

Word      1      --  Issuing    task's   name    in    Radlx-50    (second    half) 

Word      2      —  Partition    nam3    in    Radix-50    (first    half) 

Word      3      —  Partition    name    in    Radix-50    (second    half) 

Word  4  --  Undefined  in  RSX-1 IM/M-PLUS  (this  word  exists  for 
RSX-llD   compatibility) 

Word  5  --  Undefined  in  RSX-1 IM/M-PLUS  ,chis  word  exists  for 
RSX-llD  compatibil ity) 

Word      6      —      Run    priority 

Word  7  --  User  identification  code  (UIC)  of  issuing  task  (in  a 
multiuser  protection  system,  the  task's  default 
UIC)1 

Word    10      —      Number    of    logical    I/O   units    (LUNs) 

Word    11      --      Undefined    in    RSX-1  IM/M-PLUS    (this   word    exists    for 
RSX-llD   compatibility) 

Word    12      --      Undefined    in    RSX- I IM/M-PLUS     (this    word    exists    for 
RSX-llD   compatibility) 

Word    13      --       (Address    of    task    SST   vector    tables) 2 


1.  See   note    in    RQSTS   description    (Section    5.3.54)    on   contents   of    words 
07   and    17. 

2.  Words    13   and    14   will    contain   valid    data    if    word    14    is   not    zero.       If 
word    14    is    zero,    the   contents   of   word    13   are   meaningless. 
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Word  14   —   (Size  of  task  SST  vector  table  in  words) '^ 

Word  15  —  yize  (in  bytes)  either  of  task's  address  window  0  in 
mapped  systems,  or  of  task's  partition  in  unmapped 
system  (equivalent  to  partition  size) 

Word  16   --   System  on  which  task  is  running: 

0  for    RSX-llD 

1  for    RSX-llM 

2  for    RSX-llS 

3  for    IAS 

4  for    RSTS 

5  for    VAX/VMS 

6  for    RSX-llM-PLUS 

7  for    RTll    sinqle    Job   Monitor 

10    for    RTll    Foreground/Background 
and    Extended    Memory   Monitor 

Word  17  —  Protection  UTC  (in  multiuser  system,  the  log-in 
UIC)  1- 

Macro    Expansion: 

GTSK$    DATBUF 

.BYTE    63., 2  ;GTSK$  DIC,  DPB=2-W0RDS 

.WORD    DATBUF  ; ADDRESS  OF  16-WORD  BUFFER 

Local  Symbol  Definitions 

G.TSBA   —   Buffer  address  (2) 

The  following  offsets  are  assigned   relative   to   the   task   parameter 
buffer : 

G.TSTN  --  Task  name  (4) 

G.TSPN  --  Partition    name    (4) 

G.TSPR  --  Priority    (?) 

G.TSGC  --  UIC  group  code  (1) 

G.TSPC  —  Urc    memoer    code    (1) 

G.TSNL  --  Number    of    logical    units    (2) 

G.T3VA  —  Task's    SST  vector    address    (2) 

G.TSVL  —  Task's    SST   vector    length    in   words    (2) 

G.TSTS  —  Task  size  (2) 

G.TSSY  --  System  on  which  task  is  running  (2) 

G.TSDU  —  Protection  UIC  (2) 


1.  See  note  in  ROST$  description  (Section  5.3.54)  on  contents  of  words 
07  and  17. 

2.  Words  13  and  14  will  contain  data  if  word  14  is  not  zero.   If   word 
14  is  zero,  the  contents  of  word  13  are  meaningless. 
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DSW  Return  Codes: 

IS. sue   --   Successful  completion. 

lE.ADP   --   Part  of  the  DPB  or   buffer   Is   out   of   the   issuing 
task's  address  space. 

lE.SDP   --   Die  or  DPB  is  tnvalld. 
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5.?, 40   Map  Address  Window 

The  Map  Address  Window  dlrectWe  maps  an  exlatlm)  window  to  an 
attached  reqlon.  The  mapping  begins  it  a  specified  offset  from  the 
start  of  the  re<]ion.  If  the  wL.dow  is  already  mapped  elsewhere,  the 
Executive  unmap?  It  before  carrying  out  the  mapping  assignment 
described  In  the  directive. 

For  the  mapping  assslgnmcnt,  i  task  t-an  specify  any  lemjth  that  Is 
less  than  or  equal  t'<    '.      •'  : 

•  The  wir.dow  s  i  2«  specified  when  the  wlnlow  was  created 

•  The  length  remaining  between  the  specified  offset  within  the 
region  and  the  end  of  the  region 

A  task  must  be  attached  with  write  access  to  a  region  In  order  to  map 
to  It  with  write  access.  To  map  to  a  region  with  read-only  access, 
the  task  must  be  attached  with  either  read  or  write  ,i   •   . 

If  W.NLEN  is  set  to  0,  the  length  defaults  to  either  th-»  window  size 
or  the  length  remaining  In  the  region,  whichever  Is  smaller.  (:ilnce 
the  Executive  returns  the  actual  length  mapped  as  an  output  parameter, 
the  task  must  clear  that  parameter  in  the  WDB  before  issuing  the 
directive  each  time  It  wants  to  default  the  length  of  the  map.) 

The  values  that  can  be  assign  1  to  W.NOFF  depend  on  the  setting  of  bit 
WS.64B  in  the  window  status  woid  'W.NSTS): 

•  If  WK.64B  =  0,  the  offset  specified  in  W.NOFF  must  represent  a 
multiple  of  2'56  words  (51?  bytes).  Because  the  value  of 
W.NOFF  Is  expressed  in  units  of  32-word  blocks,  the  value  must 

be  I    " • Iple  of  9 . 

•  If  W;i.»i4tJ  =  1,  the  task  can  align  on  32-word  boundaries;  the 
programmer  aan  therefore  specify  any  offset  within  the  region. 

NOTE 

Applications  dependent  on  12-word  or 
64-byte  alignment  (WS.64B  =  1)  may  not 
be  compatible  wi*^,  future 

implementations  of         RSX         emulators. 

Therefore,  programmers  should  write 
applications  adaptable  to         either 

alignment  requirement.  The  bit  setting 
of  WS.64B  could  be  a  parameter  chosen  at 
assembly  time  (by  means  of  a  prefix 
file),  at  task-build  time  'as  input  to 
the  GBLDEF  option),  or  at  run  time  (by 
means   of    command    input). 

FORTRAN  Call : 

CALL    MAP    (iwdbf ,ldsl ) 

Iwdb      =      An    8 -word    integer    array    containing    a    Window    Definition 
Block     (see    Section    3.5.2.2) 

ids         =      Directive    status 
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Macro  Call : 

MAP$    wdb 

wdb   =  Window  Definition  Block  address 
Macro  Expansion: 

MAP$  WDBADR 

•BYTE  121., 2  ;MAPS    MACRO    DlC,     DPB    SIZE=?    WORDS 

.WORD         WDBADR  ;WDB    ADDRESS 

Window  Definition    Block    Parameters: 

Input   parameters: 

Array  Offset 

Element 

iwdb(l)  W.NID        —      ID  of    the    window  to    be   mapped, 

bits    0-7 

iwdb(4)  W.NRID      —      ID  of    the    region    to    which    the      window      'i 

to  be  mapped,  or  0  if  the  task  region  is 
to    be   mapped. 

iwdb(5)  W.NOFF      --      Offset,    in      32-word      blocks,      within      the 

region  at  which  mapping  is  to  begin. 
Note  that  if  WS.64B  In  the  window  status 
word  equals  0,  the  value  specified  must 
be   a   multiple   of    8. 

iwdb{6)  W.NLEN      --      Length,    in      32-word      blocks,      within      the 

region  to  be  mapped,  or  0  if  the  length 
is  to  default  to  either  the  size  of  the 
window  or  the  space  remaining  in  the 
region  from  the  specified  offset, 
whichever    Is    smaller. 

iwdb(7)  W.NSTS      —      Bit    settings^    in    the    window  status    word: 

Bit  Definition 

WS.WRT  1    if    write    access    is   desired 

WS.64B  0      for      256-word         (512-byte) 

alignment,      or      1    for    32-word 
(64-byte)    alignment 

Output    parameters: 

iwdb(6)  W.NLEN      —      Length   of      the      area      within      the      region 

actually  mapped    by   the    window 

iwdb(7)  W.NSTS      —     Bit    settings^    in    the    window  status    word: 

WS.UNM    —    1    if    the      window     was      unmapped 
first 


1.    If    you      are      a      FORTRAN      programmer,      refer      to      Section      3.5.2      to 
determine    the    bit    values    represented    by   the    symbolic    names  described. 
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Local    Symbol  Definitions: 

M.APBA  --     Window  Definition    Block   address    (2) 
DSW   Return    Codes: 

IS. sue  —     Successful    completion. 

lE.PRI  —      Privilege   violation. 

lE.NVR  --      Invalid    region    ID. 

lE.NVW  —      Invalid    address   window    ID. 

lE.ALG      —     Task    specified    an    invalid    region      offset      and      length 
combination  In        the        Window        Definition        Block 

parameter:.;      or   WS.64B    =    0    and    the   value    of   W.NOFI-'    is 
not    a   mul tl pie   of    8 . 

lE.HWR      —     Region  had   a   parity  error   or   a    load    failure. 

lE.IiJ      —     WS.RES  was   set   and    region    is   not   resident. 

lE.ADP      —      Part    of    the    DPS   or   WDB    is   out    of    the      issuing      task's 
address    space. 

lE.SDP      —      DIG   or    DPB    size    is    invalid. 

Notes : 

1.  When  the  Map  Address  Window  directive  is  issued,  the  task  may 
be   blocked    until    the    region    is    loaded. 

2.  Bit  WS.RES  in  word  W.NSTS  of  the  Window  Definition  Block, 
when  set,  specifics  that  the  region  should  be  mapped  only  if 
the    region    is   resident. 
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5.  3.41   Mark  Time 

The  Mark  Time  directive  Instructs  the  system  to  declare  a  significant 
event  after  an  indicated  time  interval.  The  interval  begins  when  the 
task  issues  the  directive;  however,  task  execution  continues  during 
the  interval.  If  an  event  flag  is  specified,  the  flag  is  cleared  when 
the  directive  is  issued,  and  set  when  the  significant  event  occurs. 
If  an  AST  entry  point  address  is  specified,  an  AST  (soe  Section  2.  J. 3) 
occurs  at  the  time  of  the  significant  event.  When  the  AST  occurs,  the 
task's  PS,  PC,  directive  status.  Wait  For  mask  words,  and  the  event 
flag  number  specified  in  the  directive  are  pushed  onto  the  issuing 
task's  stack.  If  neither  an  event  flag  number  nor  an  AST  service 
entry  point  is  specified,  the  significant  event  still  occurs  after  the 
indicated  time  interval.   See  Notes  below. 

FORTRAN  Calls: 

CALL  MARK  (e f n  ,  tmg , t nt f , i ds]  ) 

efn   =   Event  flag  number 

tmg   =   Time  interval  magnitude  (see  Note  5) 

tnt   =   Time  interval  unit  (see  Note  5) 

ids   =   Directive  status 

The  ISA  standard  call   for   delaying   a   task   for   a   specified   time 
interval  is  also  provided: 

CALL  WAIT  (tmg,tnt[ ,idsl ) 

tmg   =   Time  interval  magnitude  (see  Note  5  below) 

tnt   =   Time  interval  unit  (see  Note  5  below) 

ids   =   Directive  status 
Macro  Cal 1 : 

MRKT$    [efnl ,  :mg  ,tnt [ ,ast) 

efn   =   Event  flag  number 

tmg   =   Time  interval  magnitude  (see  last  Note  below) 

tnt   =   Time  interval  unit  (see  last  Note  below) 

ast   =   AST  entry  point  address 
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Macro    Expansion: 

MRKT$  52. , 30. , 2,MRKAST 

.BYTE  2 3., 5 

.WORD  52. 

.WORD  30. 

.WORD  2 

.WORD  MRKAST 


MRKT$   MACRO    DtC,     DPB    SIZE-5    WORDS 

EVENT    FLAG   NUMBER    52. 

TIME   MAGNITUDE  •-'30. 

TIME    UNIT=SECONDS 

ADDRESS    OF    MARK    TIME    AST    ROUTINE 


Local    Symbol    Definitions: 

M.KTEF      --      Event    flag     (2) 
M.KTMG      --      Time  magnitude    (2) 
M.KTUN      --      Time    unit    (2) 
M.KTAE      —     AST  entry   point    address    (2) 
DSW   Return    Codes: 

For    CALL   MARK    and    MRKTS: 

IS. sue        --  Successful    completion. 

--    Insufficient    dynamic    memory, 
—    Invalid    time    parameter. 


IE. JPN 
IE. ITI 
IE. lEF 


lE.ADP 


-  Invalid  event  flag  number  (EFN<0,  or  EFN>96  if 
group  global  event  flags  exist  for  the  task's 
group;      or    EFN>64    if    not). 

--    Part   of    the    DPB      is      out      of      the      issuing      task's 
address    space. 


lE.SDP        --   Die   or    DPB   size    is    invalid. 

For    CALL   WAIT: 

RSX-1 IM/M-PLUS  provides  the  following  positive  error  codes  to   be 
returned  for  ISA  calls: 

1  --  Successful  completion 

2  --  Insufficient  dynamic  storage 

3  —  Specified  task  not  installed 
94  --  Invalid  time  parameters 

98  —   Invalid  event  flag  number 

99  —   Part  of  DPB  out  c f  task's  ranqe 

100  —   Die  or  DPB  size  invalid 
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1.  Mark  Time  requires  dynamic  memory  for  the  clo>.k  queue  entry. 

2.  If  an  AST  entry  point  address  is  specified,  the  AST  service 
routine  is  entered  with  the  task's  stack  in  the  followlncj 
state : 

SP+10  -  Event  flaq  mask  word^ 
SP+06  -  PS  of  taaic  prior  to  AST 
SP+04  -  PC  of  task  prior  to  AST 
SP«-02  -  DSW  of  task  prior  to  AST 
SP+00  -  Event  flaq  number  or  zero  (If  none  was 
specified  In  the  Mark  Timo  directive) 

The  event  flag  number  must  be  removed  from  the  task's  stack 
before  an  AST  Service  Exit  directive  (see  Section  6.3.4)  Is 
executed  . 

3.  If  the  directive  is  rejected,  the  specified  event  flag  is  not 
guaranteed  to  be  cleared  or  set.  Consequently,  if  the  task 
Indiscriminately  executes  a  Wait  For  directive  tind  the  Mark 
Time  directive  it  rejeC-.ed,  the  task  may  wait  Indefinitely. 
Care  should  always  be  taken  to  ensure  that  the  directive  was 
successfully  completed. 

4.  If  a  task  issues  a  Mark  Time  directive  that  specifies  a 
common  or  group  global  event  flag  and  then  exits  before  the 
indicated  time  has  elapsed,  the  event  flag  is  not  set. 

5.  The  Executive  returns  the  code  IK.  IT!  (or  94)  in  the; 
Directive  Status  Word  if  the  directive  specifies  an  invalid 
time  parameter.  The  rime  parameter  consists  of  two 
components:  the  time  interval  magnitude  and  the  time 
interval  unit,  represented  by  the  arguments  tmg  and  tnt, 
respect Ively . 


A  legal  magnitude  value  (tmg)  Is  related  to  the  value 
assigned  to  the  time  interval  unit  (tnt).  The  unit  values 
are  encoded  as  follows: 

For  an  ISA  FORTRAN  call  (CALL  WAIT): 

0  =  Ticks.  A  tick  occurs  for  each  clock  interrupt  and 
is  dependent  on  the  type  of  clock  installed  in  the 
pystem. 

For  a  line  frequency  lock,  the  tick  rate  is  either 
50  Of  60  per  second,  corresponding  to  the  power-line 
frequency. 

For  a  programmable  clock,  a  maximum  of  1000  ticks 
per  second  is  available  (the  exact  rate  Is 
determined  at  system  generation  time). 


1.  The  event  flag  mask  word  preserves  the  Wait   For   conditions   of   a 

task   prior   to  AST  entry.  A  task  can,  after  an  AST,  return  to  a  Wait 
For  state.   Because  these  flags  and  the  other  stack  data   are   In   the 

user   task,   they   can   be  modified.    Such   modification  is  strongly 

discouraged,  however,  since  the   task   can   easily   fault   on   obscure 

conditions.    For   example,  clearing   the   mask   word   results   In   a 
permanent  Wait  For  State, 
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1  =  Milliseconds.  The  subroutine  converts  the  specified 
magnitude  to  the  equivalent  number  of  system  clock 
tlck:3.  On  systems  with  line  frequency  clocks, 
millisecond  Mark  Time  requests  can  only  be 
approx Imat ions . 

For  all  other  FORTRAN  and  macro  calls: 

1  =   Ticks,   See  definition  of  ticks  above. 

For  both  types  of  FORTRAN  calls  and  all  macro  calls: 

2  =   Seconds 

3  =   Minutes 

4  =   Hours 

The  magnitude  (tmg)  is  the  number  of  units  to  be  clocked. 
The  following  list  describes  the  magnitude  values  that  are 
valid  for  each  type  of  unit.  In  no  case  can  the  value  of  tmg 
exceed  24  hours.  The  list  applies  to  both  FORTRAN  and  macro 
calls. 

If  tnt  =  0,  1,  or  2,  tmg  can  be  .my  positive  value  with   a 
maximum  of  15  bits. 

If  tnt  =  3,  tmg  can  have  a  maximum  value  of  1440(10). 

If  tnt  =  4,  tmg  can  have  a  maximum  value  of  24(10). 

If  the  specified  event  flag  Is  a  group  global,  the  use  count 
for  the  event  flag's  group  is  incremented  to  prevent 
premature  elimination  of  event  flags.  The  use  count  Is  run 
down  when: 

•  The  Mark  Time  event  occurs. 

•  The  Mark  Time  event  is  cancelled. 

•  The  Issuing  task  exits  with  the  Mark  Time  event   still   on 
the  clock  queue  . 

The  minimum  time  Interval  is  one  tick.  If  you  specify  a  time 
interval  of  zero.  It  will  be  converted  to  one  tick. 
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MSDS$ 


5.3.42   Map  Suparvisor  D-Space 

The  Map  Supervisor  D-Space  ilrectlve  allows  the  issuing  task  to  change 
the  mapping  of  Its  supervisor-mode  D-space  APRs .  This  directive  also 
provides  Informaclon  about  the  current  mapping  of  the  task's 
supervisor-mode  D-space  APRs . 

Tasks  that  do  not  use  data  space  ex  .-cute  with  instruction  and  data 
space  overmapped.  Tasks  In  which  the  Task  Builder  has  separated 
instruction  and  data  space  are  mapped  separately  (Instruction  and  data 
space  are  not  overmapped).  The  overall  mapping  structure  foi  tiiese 
tasks  is  as  follows: 

Window  0        Root  I-space. 

Window  1        Task  header,  stack  and  root  D-gpaco. 

Window  2  I-space  of  the  read-only  section  If  a  multiuser 
task.  Memory  resident  overlays  if  not  a 
multiuser  taak. 

Window  3  D-space  of  the  read-only  section  if  a  multiuser 
task.  Memory  resident  overlays  If  not  a 
multiuser  task. 

Window  4        Memory  resident  overlays. 


When  supervisor-mode  library  code  is  executing,  the  supervisor-mode 
I-space  APRS  map  supervisor-mode  instruction  space.  However,  the 
supervisor-mode  D-space  APRs  normally  map  user-mode  dota  space.  Code 
that  resides  in  a  supervisor-mode  library  can  include  data  fsuch  as 
error  messages)  within  its  own  instruction  space.  The  Map  Supervisor 
D-5pace  directive  allows  such  code  to  use  the  superv Isur-mode  D-Space 
APRs  to  map  locations  in  supervisor-mode  Instruction  space  that 
contain  data. 

The  Map  Supervisor  D-Space  directive  allows  the  Issuing  task  to 
specify  a  7-bit  mask  that  determines  the  maoping  of  supervisor-mode 
D-space  APRs.  The  mask  value  contains  one  bit  for  each  APR  starting 
with  APR  1.  The  bits  control  the  value  stored  in  the  supervisor 
mapping  control  byte  In  the  task  header  '  H.SMAP). 

This  mask  is  stored  in  the  high  byte  of  the  parameter.  The  low  byte 
of  the  parameter  is  Ignored.  Since  the  high  bit  of  the  PSW  may  be 
set,  the  PSW  is  returned  In  t  .e  low  byte.  The  mask  Is  returned  In  tho 
high  byte.  Note  that  although  there  are  eight  APRs,  the  mask  is  only 
seven  bits  since  APR  0  may  not  be  changed.  The  mask  position  in  the 
parameter  Is  Identical  to  the  DSW  return. 
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To  provide  for  the  case  when  a  supervisor-mote  library  is  being  used 
by  some  tasks  as  a  user-mode  library,  this  directive  does  not  change 
the  task's  mapping  when  it  is  issued  from  user  mode.  However,  the  DSW 
is  Ptill  returned. 

When  the  di  ective  is  successfully  executed,  the  DSW  provides 
Information  about  the  task's  current  mapping  and  mode.  Specifying  a 
negative  mask  value  causes  the  directive  to  return  information  rather 
than  change  the  mapping. 


FORTRAN  Call : 

Not  supported 
Macro  Call; 

MSDS$    mask 


mask  =  A  7-bIt  mask  with  one  bit  corresponding  to  each 
supervisor-mode  D-space  APR.  If  the  bit  is  set,  the 
APR  is  mapped  to  supervisor-mode  I-spacc.  If  the  bit 
is  clear,  the  APR  is  mapped  to  user-mode  D-space.  The 
7  bits  are  specified  in  bits  8  through  14  of  the  mask 
word . 


Macro  Expansion: 

MSDS$  mask 
.BYTE    201. ,1 


;DIC=201.   DPB  SI7E=  1  WORD 


DSW  Return  Codes: 

IS.ADP   —   Part  of  the  DPB  is  out  of  the  issuing  task's   address 
space. 


lE.SDP   —   Die  or  DPB  size  is  invalid, 


Notes ; 


When  including  data  in  a  supervisor-mode  library,  the  library 
may  not  overmap  APR  0  with  the  supervisor-mode  library.  The 
executive  assumes  it  has  access  to  the  task's  DSW  regardless 
of  the  mode  from  which  a  directive  is  issued.  Data  must 
therefore  be  placed  near  the  end  of  the  library,  or  mapped 
through  a  memory  resident  overlay  to  force  its  mapping  into 
some  APR  other  than  0. 

In  the  following  example,  a  supervisor-mode  library  routine 
changes  its  mapping  in  order  to  access  an  error  message 
(which  is  data). 
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MESSAG:  .ASCIZ 

TST  (RO) 

BPL  10$ 

I 

MSDS$S  1100000 

MOV  SDSW.RO 

MOV  RO,-(SP) 


BIS  »400,R0 

MSDS$S  RO 

MUV  IMESSACRl 

CALL  RRROR 


MOV 
MSDS$S 

,  RETURN 


(SP)+,RO 
RO 


/    ERROR    IN    INPUT    DATA/ 

t    CHECK   SOME    PIECE   OF    USER   DATA 

;    IF    PLUS    OK 

t    GET  CURRENT  STATUS  OF  MAPPING 

;  SAVE  CURRENT  STATE  FOR  RESTORE 
;  OF  MAPPING  STATE 

;  UPDATE  MASK  TO  MAP  APR'  "0  SUPER 

;  MODE 

;    M/P   TO   SUPER    I    SPACE 

;  POINT  TO  ERROR  MESSAGE 

;  WHICH  IS  DATA 

;  ERROR  IS  A  SUBROUTINE  THAT 

J  HAS  LOCAL  ERROR  MESSAGES  IN 

;  A  SUPERVISOR  MODE  LIBRARY 

;  GET  OLD  MAPPING  STATUS 

J  RESTORE  OLD  MAPPING  STATUS 

;  BACK  TO  USER 
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5.3.43  Hove  To/Proa  Usar/Supcrvisor  I/D-8pace 

The  Move  To/From  User/Supervisor  I/D-Space  directive  Instructs  the 
system  to  fetch  data  from  a  specified  location  In  cisor-mode  or 
supervisor-mode  I-or  D-space,  or  to  write  the  specified  value  in  the 
specified  location  in  the  specified  type  of  address  space. 

This  directive  allows  you  to  access  a  single  word  of  I -space  as  data 
without  creating  a  D-space  window.  This  function  is  primarily 
intended  for  use  by  debugging  aids.  Use  of  this  directive  in 
production  code  is  not  recommended  since  the  directive  is  not 
optimized  for  performar  .-e. 

FORTRAN  Call : 

Not  supported. 

Macro  Call : 

MVTS$   action, addr,val 

buff 

action  ■=  One  of  the  following: 

MV.TUI  —  Move  to  user  I-space 

MV.TUD  --  Move  to  user  D-space 

MV.TSr  —  Move  to  supervisor  I-space 

MV.TSD  —  Move  to  supervise.-  D-space 

MV.FUI  --  Move  from  user  I-space 

MV. FUD  —  Move  from  user  D-space 

MV.FSI  --  Move  from  supervisor  I-space 

MV.FSD  --  Move  from  supervisor  D-space 

addr   =  Address  of  the  location  in  the  task 

buff   •"  Buffer  to  receive  the  value   fetched,   for   the  move 
frora  operations 


val    =  Value  to  be  stored  in  the  location,  for  the 
operations 


move   to 


Macro  Expansion: 

MVTS$  action, addr , val 

.BYTE  203., 4  ;DIC    203.,    DPB    SI/E=  4    WORDS 

.WORD  action  ;THE    OPERATION    TO   BE  PERFORMED 

•WORD  addr  ;ADDRESS    OF    THE    TASK  LOCATION 

.WORD  val  ; VALUE    TO   BE   WRITTEN  (OR    BUFFER    IF    MOVE    FROM) 

Local    Symbol    Definitions: 

M.VTAC      —      Action    code 

M.VTAD      —     Address   of   location    in    I/D   space    to    bo      moved      to      or 
from 

M.VTBF      —     Buffer    address   or 

or  -, 

M.VTVA  Value    to    be   moved 
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DSW  Return  Codes: 

IE. SOP   —   Die  or  DPB  size  Is  invalid. 

lE.ADP   —   Part  of  the  DPB  is  out  of  the  issuing  task's  address 

space;    the  specified  address  Is  not  mapped;  or  the 

buffer  or  the  target  address  Is  not   in   the  Issuing 
task's  address  space. 

lE.PRI   —   The  issuing  task  does  not  have  write   access   to   tht 
target  address. 
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QIO$ 


5.3.44   Queue  I/O  Request 

The  Queue  I/O  Request  directive  instruct*  th«  system  to  place  an  I/O 
request  for  an  indicated  physical  device  unit  into  a  queue  of 
priority-ordered  requests  for  that  device  unit.  The  physical  device 
unit  Is  specified  as  a  logical  unit  number  (LUN)  assigned  to  the 
device. 

'''he  Executive  declares  a  significant  event  whwn  tht>  I/O  transfer 
completes.  If  the  directive  call  specifics  .in  event  flag,  the 
Executive  clears  f he  flag  when  the  request  is  queued  and  sets  the  flag 
when  the  significant  event  occurs. 

The  I/O  status  block  Is  also  cleared  when  the  request  is  queued  and  Is 
set  to  the  final  I/O  status  when  the  I/n  request  is  complete.  If  an 
AST  service  routine  entry  point  address  is  specified,  the  AST  occurs 
upon  I/O  completion,  and  the  task's  Walt  For  mask  word,  PS,  PC,  DSW, 
and  the  address  of  the  I/O  status  block  are  pushed  onto  the  task's 
stack. 

The  description  below  deals  solely  with  the  Executive  directive;  the 
device-dependent  information  can  be  found  in  the  RSX-1 IM/M-PLUS  I/O 
Dr 1  vers  Reference  Manual .   See  Notes  below. 

FORTRAN  Call : 

CALL  010  (fnc,lun, [efn) , (prl) , [ isb] , [prll [,ldsl ) 

fnc   =  I/O  function  code^ 

lun   =  Logical  unit  number 

efn   =  Event  flag  number 

pr  i   =  Priority;   ignored,  but  must  be  present 

A  2-word  integer  array  to  receive  final  I/O  status 


isb 
prl 

ids 
Macro    Cal 1 ; 
QIOS 
fnc 
lun 


A  6-word  integer  array  containing  device-dependent 
parameters  to  be  placed  in  parameter  words  I  through  fi 
of  the  DPB.  Fill  in  this  array  by  using  the  GETADR 
routine    (see    Section    l.S.1.4). 

Directive    status 


fnc , 1 un  ,  [ ef n  i  , ' pr  i ] , [isb] , [ast ) , ( pr 1 
=      I/O    function    code ^ 
=      Logical    unit    number 


1.     T/O    function    code   definitions    are    included       in       the      Rjf  Xjil  i^M/M-PLUS 
I/O   Drivers    Reference   Manual. 
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OIOS 

lO.RVB 

.BYTE 

I,  12. 

.WORD 

lO.RVB 

.WORD 

7 

.BYTE 

52.  ,0 

.WORD 

lOSTAT 

.WORD 

tOAST 

.WORD 

lOBUFR 

.WORD 

512. 

.WORD 

0 

.WORD 

0 

.WORD 

0 

.WORD 

0 

efn      »      Event    flag    number 

prl      ■      Priority;      ignored,    hut   must    be   prestnt 

Isb      »     Address   ot    I/O  status   block 

ast      "      Address   of   entry   point   of    AST  service    routine 

prl      «      Parameter    list    of    the    form    <Pl,...P6> 

Macro    Expansion; 

IO.RVB,7,52.,, lOSTAT, lOAST,^  I OBUFR, 51 2. > 

QIO$    MACRO    Die,     DPI)    .SIZE-12 
FUNCTION=READ    VIRTUAL   BLOCK 
LOGICAL    UNIT    NUMBER    7 
;EFN    52.,     PRIORITY    IGNORED 
ADDRESS    OF    2-WORD    I/O    STATUS    BLOCK 
ADDRESS    OF    I/O    AST    ROUTINE 
ADDRESS    OF    DATA    BUFFER 
BYTE    COUNT-512. 
ADDITIONAL    PARAMETERS .. , 
, , .NOT    USED    IN. . . 
. . .THIS    PARTICULAR. . . 
...INVOCATION    OF    OUEUE     I/O 

Local    Symbol    Definitions: 

0. lOFN      --      I/O    function   code    (2) 

Q.  lOLU      --      Logical    unit    number    (2) 

Q. lOEF      --      Event    flag    number    (1) 

Q.IOPR      --      Priority    (1) 

Q.IOSB      --      Address   of    I/O   status   block    (2) 

Q.IOAE      --      Address    of    I/O   done    AST   entry   point    (2) 

Q.IOPL      —      Parameter    list    (6   words)     (12) 

DSW    Return    Codes: 

IJ.SUC      —      Successful    completion. 

Insufficient   dynamic   metrory. 

Unassiqned     LUN. 

Device    driver    not    loaded. 


lE.UPN 
lE.ULN 
lE.HWR 
IE. PR  I 


Task   other    than   despooler    attempted    a      write      logical 
block   operation. 

IE.  ILU       --       Inval id    LUN. 

lE.IEF  --  Invalid  event  flag  number  (EFN<n,  or  EFN>96  if  group 
global  event  flags  exist  for  the  task's  group;  or 
EFN>64    i  f    not)  . 

lE.ADP  —  Part  of  the  DPU  or  I/O  status  block  is  out  of  the 
issuing    task's    address    space. 

lE.SDP      --      Die   or    DPB   size    is    invalid. 
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li  the  directive  call  specifics  an  AlIT  en'ry 
the  task  enters  the  AST  service  routine  with 
followlnq  atate: 


point   address, 
its  stack  in  the 


SP+10  -  Event  flaq  mask  word 

SP  +  06  -  PS  of  task  prior  to  Al'.T 

SP«-04  -  PC  of  task  prior  to  AST 

SP+02  -  DSW  of  task  prior  to  AST 

SP+00  -  Address  of  I/O  status  block,  or  zero, 
was  specified  in  the  QIO  directive 


I f  none 


The  address  of  the  I/O  status  block,  which  Is  a 
trap-iependent  parameter,  must  be  removed  from  the  task's 
stack  before  an  AST  Service  Exit  directive  (see  Section 
S. 3. 4)  is  executed  . 

If  the  directive  Is  rejected,  the  specified  event  flaq  Is  not 
quaranteed  to  be  cleared  or  set.  Consequently,  If  the  task 
Indiscriminately  executes  a  Walt  For  or  Stop  For  liroctive 
and  the  QIO  directive  Is  rejected,  the  task  m^y  wait 
Indefinitely.  Care  should  always  be  taken  to  ensure  that  the 
directive  was  successfully  completed. 

Tasks  (or  reqions  on  RSX-llM-PLUS  systems)  cannot  normally  be 

checkpo  i  ntP')  with  I/O  out  s  t  <iiid  i  rr)  t  ir  two  reasons: 

•  If  tho  310  directive  results  in  a  data  transfer,  the   dat,i 
transfers  directly  to  or  from  the  user-specified  buffer. 

•  If  an  I/O  status  block  address  is  specified,  the  directive 
status  is  returned  directly  to  the  I/O  status  block. 

The  Executive  waits  until  a  task  has  no  outstandinq  I/O 
before  initlatinq  checV.po  int  inq  In  all  cases  except  the  one 
described  below. 

In  systems  that  support  buffered  I/O,  drivers  that  buffer  I/O 
check  for  the  followlnq  conditions  for  a  task: 

•  That  the  task  is  checkpointable 

•  That  checkpointing  is  enabled 

If  those  two  conditions  are  met,  the  driver  and/or  the 
bxecutive  buffers  the  I/O  request  Internally  and  the  task  Is 
checkpointable  with  this  outstandinq  I/O.  If  the  task  also 
entered  a  Wait  For  state  when  the  I/O  was  Issued  (see  the 
0IOW$  directive)  or  subsequently  enters  a  Walt  For  state,  the 
task  Is  stopped.  Any  competinq  task  waltinq  to  he  loaded 
into  the  partition  can  checkpoint  the  stopped  task, 
reqardless  of  priority.  If  the  stopped  task  is  checkpo  Ir.ted , 
the  executive  does  not  brlnq  it  back  into  memory  until  the 
stopped  state  is  terminated  by  completion  of  buffered  I/O  or 
satisfaction  of  the  Wait  Fo"-  condition. 


Not  all  drivers  buffer  I/O  requests. 
an  example  of  one  that  does. 


The  terminal  driver   is 
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4.  A  privileged  task  on  RSX-1 IM  and   any  task  on   RSX-llM-PLUS 

that   Is   linked   to   a  common  (read-only)  area  can  issue  gio 
write  requests  to  that  area. 

5.  If  the  specified  event  flaq  I3  a  group  global,  tlie  use  count 
for  the  event  flag's  group  is  Incremented  to  prevent 
premature  elimination  of  the  event  flags.  The  use  count  is 
run  down  when : 

•  The  I/O  is  completed. 

•  Th«  r/0  is  killed  by  reassigning  the   specified   LUN   with 
the  ALUNS  directive. 

•  The  I/O  is  killed  by  Issuing  the  lO.KIL  function   for   the 
specified  LUN. 

•  The  task  exits  befo:e  I/O  is  completed. 
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QIOW$ 

5.3.45   Queue  I/O  Request  rnd   W.ilt 

The  Queue  I/O  Request  And  Wn i t  directive  Is  Identical  to  the  Queue  I/O 
Request  In  all  but  one  aspect.  If  the  Wait  variation  of  the  directive 
specifies  an  event  flag,  the  Executive  automatically  effects  a  Wait 
For  Singli  Event  Flag  directive.  If  an  event  flag  Is  not  specified, 
however,  the  Executive  treats  the  directive  as  If  It  were  a  simple 
Queue  I/O  Request. 

The  following  description  lists  the  FORTRAN  and  macro  calls  with  the 
associated  parameters,  as  well  as  the  macro  expansion.  Consult  the 
description  of  Queue  I/O  Request  for  a  definition  of  the  parameters, 
the  local  symbol  definitions,  the  DSW  return  codes,  and  explanatory 
notes. 

FORTRAN  Call : 

CALL  WTOro  (fnc,lun, [efn] , tpr 1 1  , f isb) , [prll  (  ,idsl ) 

fnc   "  I/O  function  code^ 

lun   =  Logical  unit  number 

efn   =  Event  flag  number 

pr i   =  Priority;   ignored,  but  must  be  present 

isb   =  A  2-word  integer  ?rray  to  receive  final  I/O  status 

prl  =  A  6-word  integer  array  containing  device-dependent 
parameters  to  be  placed  in  parameter  words  1  through  6 
of  the  DPB 

ids  =  Directive  status 

Macro  Cal  1  : 

grows  fnc,lun, [efn] , fprll , ( isb] , [ast] [,prl] 

fnc  =  I/O  function  code^ 

lun  =  Logical  unit  number 

efn  =  Event  flag  number 

pr i  =  Priority;   ignored,  but  must  be  present 

isb  =  Address  of  I/O  status  block 

ast  =  Address  of  entry  point  of  AST  service  routine 

prl  =  Parameter  list  of  the  form  <P1,...P6> 


1.  I/O  function  codes  are  defined  in  the   RSX-1 IM/W-PLUS   I/O   Drivers 
Reference  Manual. 
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rtacro    Expansion; 


QIOWS 

lO.RVB 

.BYTE 

3,  12. 

.WORD 

lO.RVQ 

.WORD 

7 

.BYTE 

52. ,0 

.WORD 

rOSTAT 

.WORD 

I  OAST 

.WORD 

lOBUFR 

.WORD 

512. 

.WORD 

0 

.WORD 

0 

.WORD 

0 

.WORD 

0 

I0.RVB,7,  52.  ,  ,  lOSTAT,  lOA.ST,  <  U  "^'jFR,  512.  > 

)QIO$    MACRO    DIG,     DPB    SUE-12. 
;FUNCTION=READ    VIRTUAL    BLOCK 
; LOGICAL    UNIT    NUMBER    7 
;SFN    52.,     PRIORITY    IGNORED 
/ADDRESS    OF    2-WORD    WO    STAT"JJ    BLOCK 
ADDRESS    OF    I/O    AST    ROUTINfc 
ADDRESS    OF    DATA    BUFFER 
BYTE    COUNTY'S  I  2. 
;AUDITIONAt,    PARAMETERS... 
. .NOT    USED    IN. . . 
.  .THIS    PARTICULAR.  .  . 
..INVOCATION    OF    QUEUE    I/O 
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RCST$ 

5.?. 46   Receive  Data  Or  Stop 

The  Receive  Data  Or  Stop  directive  Instructs  the  system  to   dequeue   a 

13-word   data   block   for  the  Issuing  task;  th«>  data  block  was  queued 

for  the  task  with  a  Send  Data  Directive  or  a  Send,  Request  ana  Connect 
d  i  rect Ive . 

A  2-word  task  name  of  the  sender  (In  Radix-50  format)  and  the  13-word 
data  block  are  returned  in  an  indicated  15-word  buffer.  The  task  name 
is  contained  in  the  first  two  words  of  the  buffer. 

If  no  data  has  been  sent,  the  issuing  task  Is  stopped.  In  this  case, 
the  sender  task  is  expected  to  Issue  an  Unstop  directive  after  sending 
data.  A  success  status  code  of  IS.SUC  Indicates  that  a  packet  has 
been  received.  A  success  status  code  of  IS. SET  indicates  that  the 
task  was  stopped  and  has  been  unstopped.  The  directive  must  then  be 
reissued  to  retrieve  the  packet. 

When  a  slave  task  issues  the  Receive  Data  or  Stop  directive,  it 
assumes  the  UIC  (if  it  has  no  outstanding  group  global  context)  and 
TI:   terminal  of  the  task  that  sent  the  data. 

FORTRAN  Call  : 

CALL  RCST  ( [rtname] ,lbuf ( ,ids] ) 

rtname   =   Sender  task  name  (if   not   specified,   data   may   be 
ieceived  from  any  task.) 

Ibuf     =   Address  of  15-word  buffer  to  receive  the  sender  task 
name  and  data 

Ids      =   Integer  to  receive  the  directive  status  word 

Macro  Cal 1 : 

RCST$         [tname] ,buf 

tname        =      Sender    task   name    (If      not      specified,      data      may      be 
received    from    any    task.) 

buf  =      Address    of    15-word    buffer    to    receive    the    sender    task 

name   and    data 

Macro    Expansion: 

RCSTS  ALPHA, TSKBUF 

.BYTE  139., 4  ;RCST$    MACRO    DlC,     DPB    SIZE=4    WORDS 

.RAD50  ALPHA  ;DATA    SENDER    TASK   NAME 

•  WORD  TSKBUF  .-BUFFER    ADDRESS 

Local    Symbol    Definitions: 

R.CSTN      —      Task    name    (4) 

R.CSBF      —      Buffer    address    (2) 
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DSW  Return  Codes: 

IS. sue   --   Successful  completion. 

IS. SET  --  No  data  was  received  and  task  was  stopped  (note  that 
the  task  must  be  Unstopped  before  It  can  see  this 
status)  . 

lE.RSU  --  The  Issuing  task  Is  a  slavt  taak  with  a  qroup  global 
context  active,  and  th«  n«xt  packet  received  would 
have  changed  the  task's  group  number. 

IE. AST   —   The  Issuing  task  is  at  AST  state. 

lE.ADP  —  Part  of  the  DPB  Is  out  of  the  Issuing  task's  addrasa 
apace. 

IE. SOP   --   Die  or  DPB  size  Is  Invalid. 


Note: 


In  RSX-llM-PLUS  systems  that  support  variable  aend  and  racaWa 
directives  (secondary  pool  support  SYSGEN  option),  the  Receive 
Data  Or  Stop  directive  is  treated  aa  a  13.  word  Variable  Receive 
Data  Or  Stop  directive  (see  Section  5.3.88). 
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RCVD$ 

5.3.47   Receive  Data 

The  Recj ive  Tata  directive  Instruct?  the  system  to  dequeue  a  13-word 
data  block  for  the  Issuing  task;  the  data  block  has  been  queued 
(FIFO)  for  the  task  by  a  Send  Data  Directive. 

A  2-word  sender  task  name  (In  Radlx-50  form)  and  the  13-word  data 
block  are  returned  In  !\r\  Indicated  15-word  buffer,  with  the  task  name 
in  the  first  two  words. 

When  a  slave  task  Issues  th**  Receive  I)ata  directive,  it  assumes  the 
UIC  (if  it  has  no  outstanding  group  global  event  flag  contexts  and  TI; 
terminal  of  the  task  that  sent  the  data. 

FORTRAN  Ca  1 1  : 

CALL  RECEIV  ( ( tsk 1  , buf [  ,  ,  ids  1 ) 

tsk   =   Sender  task  name  (If  not  specified,  data  may  be 
received  from  any  task.) 

buf  =   A  15-word  integer  array  for  received  dat  i 

Ids  =   Directive  status 

Macro  Call : 

RCVD$         [tskl,bu£ 

tsk      =      Sender    task   name    (If    not    specified,    data   may   be 
received    from    any   task.) 

buf      =      Address   of    15-word    buffer 

Macro    Expansion: 

;TASK    NAME    AND    BUFFER    ADDRESS 
;RCVDS    MACRO    niC,     DPB    SIZE=4    WORDS 
; SENDER    TASK    NAME 
/ADDRESS    OF     15. -WORD   BUFFER 

Local    Symbol    Definitions: 

R.VDTN      —      Sender    task    name    (4) 
R.VDBA      --      Buffer    address    (2) 

DSW    Return    Codes: 

IS. sue      —      Successful    completion- 
IE.  ITS      —      No    data    currently   queued. 

lE.RSU  —  The  issuing  task  is  a  slave  task  with  a  group  global 
context  active,  and  the  next  packet  to  be  received 
would    have    changed    the    cask's   group   number. 

lE.ADP  —  Part  of  the  DPB  or  buffer  is  out  of  the  issuing 
task's    address    spa<.:e. 

lE.SDP      —      Die    or    DPB    size    is    invalid. 
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ALPHA, DATBUF 

.BYTE 

75.  ,4 

.RAD50 

/ALPHA/ 

.WORD 

DATBUF 

DIRECTIVE  DBSCniPTIONS 


Notes : 


1.  In  RSX-llM-PLUS  systams  thti  support  variable  sand  and 
racalva  diractlves  (aacondar/  pool  support  SYSCEN  option), 
the  Receive  Data  directive  Is  treated  aa  a  13.  word  Variable 
Receive  Data  directive  (see  Section  S.3.fl7). 

2.  If  the  sending  task  specifies  a  oommon  or  group  global  event 
flag  In  the  Send  Data  directive,  the  receiving  task  may  use 
that  event  flag  for  synchronization.  However,  between  the 
time  that  the  receiver  issues  this  directive  and  the  time  the 
receiver  Issues  It's  noxt  Instruction,  the  sender  can  send 
data  and  set  the  event  flag.  If  the  next  lnsttuct<on  is  an 
Exit  directive,  any  data  sent  during  this  time  will  be  lost 
because  the  Executive  flushes  the  task's  receive  list  a&  part 
of  exit  processing.  Therefore,  use  the  Exit  If  directive  or 
the  Receive  Data  or  Exit  directive  In  order  to  avoid  the  tace 
cond 1 t lo^ . 
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RCVX$ 


5.3.48  Receive  Data  Or  Exit 

The  Receive  Data  Or  Exit  directive  Instructs  the  system  to  dequeue  a 
13-word  data  block  for  the  issuing  task;  the  data  block  has  been 
queued  (FIFO)  for  the  task  by  a  Send  Data  directive. 

A  2-word  sender  task  name  (in  Radix-50  form)  and  the  13-word  data 
block  are  returned  in  an  indicated  15-word  buffer,  with  the  task  name 
in  the  first  two  words. 

If  no  data  has  been  sent,  a  task  exit  occurs.  To  prevent  the  possible 
loss  of  Send  packets,  the  user  should  not  rely  on  I/O  rundown  to  take 
care  of  any  outstanding  I/O  or  open  files;  the  task  should  assume 
this  responsibility. 

When  a  slave  task  issues  the  Receive  Data  Or  Exit  directive.  It 
assumes  the  UIC  (if  it  has  no  outstanding  group  global  event  flag 
context)  and  TI:  terminal  of  the  task  that  sent  the  data.  See  Notes 
below. 

FORTRAN  Call : 

CALL  RECOEX  ( [  tsk]  , buf  [  ,  ,  Us]  ) 

tsk 


buf 

ids 

Macro  Call : 

RCVX$ 

tsk 

buf 


Sender  task  name  (If  not  specified,  data  may  be 
received  from  any  tjsk.) 

A  15-worr)  integer  array  Cor  received  data 

Directive  status 


[tsk] ,buf 

Sender  task  name  (If  not  specified,  data  may  be 
received  from  any  task.) 


Address  of  15-word  buffer 


Macro  Expansion: 

TASK  NAME  AND  BUFFER  ADDRESS 
RCVX$  MACRO  Die,  DPD  SIZE=4  WORDS 
SENDER  TASK  NAME 
ADDRESS  OF  15. -WORD  BUFFER 

Local  Symbol  Definitions: 

R.VXTN  --      Sender  task  name  (4)  R.VXBA   =   Buffer  address  (2) 


RCVX? 

ALPHA, DA TBUF 

.BYTE 

77. ,4 

.RAD50 

/ALPHA/ 

.WORD 

DATBUF 
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DSW   Return   Codes: 

IS. sue      —     Surcoisful    compleytilon. 

I2.RSU  —  The  Issuing  task  Is  a  slave  lask  wl-h  a  group  global 
context  active,  and  the  next  n-.oket  to  bq  received 
would   have   changed    the   tark's  group  number. 

lE.ADP  —  Part  of  the  DPB  or  buffer  is  out  of  the  Issilng 
task's   address   space. 

lE.SDP      —      DIG   or    DPB    size    is    Invalid. 


Notes: 

1, 


• 


A  FORTRAN  program  th&t  Issues  the  RECOEX  call  must  first 
close  all  files  by  issuing  CLOSE  calls.  Sea  the  IAS/RgX-11 
FORTRAN  IV  or  the  FORTRAN  IV-PLUS  User's  GuTae  ToT 
Trstriictions  concerning  how  to  ensure  that  such  files  are 
closed  properly  If  the  task  exits. 

To  avoid  the  time  overhead  involved  In  the  closing  and 
reopening  of  files,  the  task  should  first  Issue  the  RECEIV 
call.  If  the  directive  status  indicates  that  no  data  were 
received,  then  the  task  can  close  all  files  and  ijsue  the 
call  to  RECOEX.  The  following  example  illustrates  the  sam" 
overhead  saving  in  MACRO: 


RCVBUP:  .BLKW    15. 

START:   RCVXSC   , RCVBUP 

CALL     OPEN 
PROC: 

Procass  packet  of  data 


;  Receive  buffer 

'  Attempt  to  receive  measaqe 

;  Call  user  subroutine  to  open  files. 


RCVDSC   .RCVB'JP 
BCC      PROC 
CALL     CLOSE 


JMP 


START 


Attempt    to    receive    another    message 
If    CC   successful    receive 
Call    user    subroutine   to    close    files 
and    prepare    for    possible    task   exit 
Make    one    last    attempt    at    receiving 


If  no  data  have  been  sent,  that  is.  If  no  Send  Data  directive 
has  been  Issued,  the  task  exits.  Tend  packets  may  be  lost  if 
a  task  exits  with  outstanding  I/O  or  open  tiles  (see  third 
paragraph   of    this    section). 


The  Recei 

ve  Da 

possible 

race 

communica 

ting 

condition 

occ 

and  finds 

its 

exit,  the 

othe 

because  the  Ex 

queue   wh 

en   1 

receiving 

task 

If  the  receive 

before  th 

e  oth 

data  can 

occur 

ta    Or    Exit    directive    is    useiul       in 

condition  that  can  occur  betwe 
by  Lhe  Send  a:id  Receive  directives, 
urs  when  one  task  executes  a  Recei 
receive  queue  empty;  but  before  th 
r  task  sends  it  a  message.  The  mes 
ecutive  flushes  the  receiver  tas 
t  exits.  This  condition  can  be  ov 
's  executing  a  Receive  Data  Or  Exit 
queue  is  found  to  be  empty,  a  task 
er    task   can    send    any  data;      thus, 


avoiding  a 
en  two  tasks 
The  race 
ve  directive 
c  task  can 
sage  Is  lost 
k's  receive 
oided  by  the 
d  i  recti vfc . 

exit  occurs 
no      loss      of 
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4.   On  Exit,  the  Executive  frees  task  resources.   In   particular, 
the  Executive: 

•  Detaches  all  attached  devices 

•  Flushes  the  AST  queue  and  despeclfles  nil  specified  ASTs 

•  Flushes  the  receive  and  recelve-by-ref erence  queues 

•  Flushes  the  clock  queue  for  outstandln>j  Mark  Time  requests 
for  the  task 

•  Closes  all  open  files  (files  open   for   write   access   are 
locked) 

•  Detaches  all  attached  regions  except   In   the  case   of   a 
fixed  task,  where  no  detaching  occurs 

•  Runs  down  the  task's  I/O 

•  Deaccasses  the  group  global  event   flags   for   the   task's 
group 

•  Disconnects  from  interrupts 
Flushes  all  outstanding  CLI  command  buffers  for  the  task 
Returns  t    success  status  (EXSSUC)  to  any  parent  tasks 


In   RSX-llM-PLUS  systems,   marks   for  deallocation   all 
virtual  terminal  units  the  task  has  created 

Breaks  the  connection  with  any  offspring  tasks 

Frees  the  task's  memory  if  the  exiting  task  was  not  fixed 


IE  the  task  exits,  the  Executive  declares  a  significant 
event . 

In  RSX-llM-PLUS  systems  that  support  variable  send  and 
receive  directives  (secondary  pool  support  SYSGEN  option), 
the  Receive  Data  Or  Exit  directive  is  treated  as  a  13-word 
Variable  Receive  Data  Or  Exit  directive  (see  Section  5.3.89) 
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5.3.49   Read  AM  Event  Flags 

The  Read  .I"  :.  nt  Flags  directive  Inbcructs  the  system  to  read  all  64 
event  flagj.  for  the  Issuing  task  and  recora  their  polarity  In  a  64-blt 
(4 -word)  bufter. 


NOTE 

This        directive        does  not  return 

group-global      event       flags       (event    flaqs 
6S    -   96)  .  ^ 

FORTRAN  Call  : 

A  FORTRAN  task  can  read  only  one  event  flag.   The  call  is: 
CALL  READEF  (efn[ .ids] ) 
efn   =   Event  flag  number 
ids   =   Directive  status 

The  Executive  returns  the  status  codes  IS. SET   (+02)   and   IS.CLR 
(00)  for  FORTRAN  calls  In  order  to  report  event  flag  polarity. 

Macro  Cal 1 : 

RDAFS    buf 
Buffer  Format: 

Word      0      —      Task    Local    Flags    1-16 

Word       1       --      Task    Local    Flags    17-32 

Word      2      —      Task    Common    Flags    33-48 

Word       3      —      Task    Common    Flags    49-64 
Macro    Expansion: 

RDAFS  FLGBUF 

.BYTE  39., 2  ;RDAFS   MACRO    DIC,     DPB    SIZE=?    WORDS 

.WORD  FLGBUF  .-ADDRESS    OF     4-WORD    BUFFER 

Local    Symbol    Definitions: 

R.DABA      —      Buffer    address    (2) 
DSW    Return    Codes: 

IS. sue      —      Successful    completion. 


lE.ADP      - 

lE.SDP      —      Die    or    DPB    size    is    invalid 


Part   o      the    DPB    or      buffer      is      out      of      the      issuing 
task's    address    space. 
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RDEF$ 

5.i.50   Read  Event  Flag 

The  Read  Event  Flag   directive   tests   an   Indicated   event   flag   and 
reports  Its  polarity  In  the  DSW. 

FORTRAN  Call : 

CALL  READEF  (lefn[,ld8l) 

ieCn      =      Integer    containing    an    Event    Flag    Number 

Ids        "      Integer    variable    to    receive    fhe    Directive    Status   Word 

Macro   Call : 

RDEFS   efn 

etn      ■      Event    flag    number 

Macro    Expansion: 

RDEF$      6 
.BYTE       37. ,2 
.WORD      6 

Local    Symbol    Definitions: 

The  following  symbol  is  locally  defined  with  Its  assigned  value 
equal  to  the  byte  offset  from  the  start  of  the  DPB  to  the  DPB 
element : 

R.DEEF    --   Event  flag    numbt»r    (length    2    bytes) 
DSW   Return    Codes: 

IS. CLP      —      Flag    was  clear. 

IS. SET      --      Flag    was  set. 

lE.IEF      --      Invalid    event    flag    number    (event    flag      number      <1      or 
>96.) . 

lE.ADP      —      Part   of    DPB    Is   out   of    Issuing    task's   dddiesa    space. 
lE.SDP      --      Die   or    DPB    size    is    invalid. 


d 
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5.3.51      Read    Extended    Evpnt    Flags 

The  Read  Extended  Event  Flags  directive  Instructs  the  system  to  read 
all  local,  common,  and  group-global  event  fl'ags  for  the  Issuing  task 
and    recortJ    their    polarity    In    a   96-blt    (6-word)    buffer. 

FORTRAN    Call : 

A   FORTRAN   task   can    read    only   one   event    flag.      The   call    la: 

CALL    READEF    (efn( .Ids] ) 

efn      =      Event    flag    number 

Ids      =      Directive    status 

The    Executive    returns    the    status   codes    If. SET      (+02>      and      IS.CLR 
(00)     for    FORTRAN   calls    to    report    event    flar    polarity. 

Macro   Cal 1 : 

RDXF$        buf 
Buffer    Fomt: 

Word      0      --      Task    Local    Flags    1-16 

Word       1      --      Task    Local    Flags    17-32 

Word      2      --      Task   Common    Flags    33-48 

Word       3      --      Task    Common    Flags    49-64 

Word      4      --      Task   Group-Global    Flags    65-80 

Word       5      --      Task    Group-Global     Flags    81-96 

Macro    Expansion: 

RDXFS  FLGBUF 

.BYTE  39., 3  ;RDXF$    MACRO    DIC,     DPB    SIZE=3   WORDS 

.WORD  FLGBUF  .-ADDRESS    OF    6-WORD   BUFFER 

Local    Symbol    Definitions: 

R.DABA      —      Buffer    address    (2l 
DSW    Return    Codes: 

IS. sue      —      Successful    completion. 

IS.CLR      —      Group-global    event    flags    do    not    exist.      Words    4    and    5 
of    the    buffer    contain   0. 

lE.ADP      --      Part   oL    the    DPB   or      buffer      is      out      of      the      issuing 
task's   address   spare. 

TS.SDP      —      DIC   or    DPB    size    is    invalid. 
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RMAFSS 

5.3.S2   I^anov*  Affinity  ($S  Forn  Reroamended) 

The  Remove  Affinity  directive  rtmoves  the  task's  CPU  afflrlty  that  was 
previously  established  by  Issuing  a  Set  Affinity  directive.  Note  that 
only  the  $S  form  Is  available  for  this  directive. 

PORTPAN  Call : 

CALL  RMAF  [  (  Ids)  1 

Ids        =      Integer    tc    receive    Directive    Status   Word 
Macro    Ca 1 1  : 

RMAFSS 
Macro    Expansion: 

;PUSH    DPB    ONTO    THE    STACK 

;RMAFSS    MACRO    DIC,     DPB    SIZE-l    WORD 

;TRAP   TO    EXECUTIVE 

Ixjcal    Symbol    Definitions: 

None 
DSW  Return   Codes: 

IS. sue      —      Successful    completion. 

IB.ADP      —      Part   of    the    DPB    is  out   of    the    issuing    taste's      addres'- 
spcice. 

lE.Si/P      —      DIC   or    DPB    size    is    Invalid. 

IE.  ITS      --      Task    installed    with   affinity. 


RMAFSS 

■ 

MOV 

(PC)+,-(SP) 

.BYTE 

163. , 1 

EMT 

377 

Note: 


A  task  that  is  installed  with  task  affinity  must  not  Iss"!"  this 
directive.  Any  attempt  to  do  so  results  in  an  IE.IT>.  trror 
returned . 


1 
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5.3.D1  Request  and  Pass  Offspring  Information 

This  directive  instructs  the  system  to  request  the  specified  task,  and 
to  chair,  to  it  by  passing  any  or  all  of  the  parent  connections  from 
the  issuing  task  to  the  requested  task.  Optionally,  the  directive  can 
pass  a  command  line  to  the  requested  task.  Only  a  privileged  or  CLI 
task  may  specify  the  UIC  and  TI:   uf  the  requested  task. 

FORTRAN  Call : 

CALL  RPOI  (tname , 1 iugc] , [ iumc] , [ iparen] , [ ibuf ] , [ ibf 1 1 , [ isc] , 
[idnam] , [iunitl , [itask] , [ocbad]  f , ids] ) 

tname  =  Name  of  an  array  containing  the  actual  name  (in 
RAD50)  of  the  task  to  be  requested  and  optionally 
chained  to. 

iugc  =  Name  of  an  integer  containing  the  group  code  number 
for  tho  UIC  of  the  requested  target  chain  task. 

iumc  =  Name  of  the  integer  containing  the  member  code  number 
for  the  UIC  of  the  requested  target  chain  task. 

iparen  =  Name  of  an  array  (or  1*4  integer)  containing  the 
RAD50  name  of  the  parent  task.  This  is  returned  in 
the  information  buffer  of  the  GTCMCI  subroutine. 

ibuf  =  Name  of  an  array  that  contains  the  command  line  text 
for  the  chained  task. 

ibfl  =  Name  of  an  integer  that  contains  the  number  of  bytes 
in  the  command  in  the  ibuf  array. 

: sc  =  Flag  byte  controlling  the  actions  of  this  directive 
request  when  executed.  The  bit  definitions  of  this 
byte  (only  the  low  order  byte  of  the  integer 
specified  in  the  call  is  «;ver  used)  are  as  follows: 

RP.OEX  =  128.   Force  this  task  to  exit  on 

successful  execution  of  the  RPOi 
directive. 

RP.OAL  =  1     Pass  all  ot  this  task's 

connections  to  the  requested 
tasK.   (The  default  is  none.) 

NOTE 

You  cannot  pass  all 
connections  if  the  target 
task  is  a  CLI  task. 

RP.ONX  =  2     Pass  the  first  connection 

in  the  queue  if  there  is  one. 
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Idnam  =  Name  of  an  integer  containing  the  ASCII  device  name 
of  the  requested  task's  TI : 

iunit  =  Name  of  an  integer  containing  the  unit  number  of  the 
requested  tasks  TI:   device. 

Itask  =  Name  of  an  array  which  contains  the  RAD50  name  the 
requestor!  task  is  to  run  under.  On  RSX-1 IM  systems, 
this  argument  is  valid  only  if  the  issuing  task  is  a 
CLI  task. 

On  RSX-llM-PLUS  systems,  any  task  may  specify  a  new 
name  for  Lhe  requested  task.  However,  the  requested 
(specified  in  the  tname  parameter)  task  must  be 
installed  in  the  ...tsk  format  and  must  not  be  a  CLI 
task . 

ocbad  =  Name  of  an  integer  containing  the  pool  address  of  the 
parent  OCB.  This  value  may  only  be  obtained  in  the 
information  buffer  of  the  GTCMCI  subroutine,  which 
only  d  CLI  can  issue,  so  therefore,  only  a  CLI  can 
specify  this  argument. 

ids  =  Name  of  en  integer  to  receive  the  directive  status 
word 


Macro  Call 


RPOI$  tname, ,,[ ugc] , [umc] , [parent]  ,  [ bufadr ]  , [buf len] , [s  c]  ,  (dnam] , 
[unit] ,  [task] , [ocbad] 

tname   =   Name  of  task  to  be  chained  to 

ugc    =  Group  code  for  UIC  of  the  requested  task 

umc    =   Member  code  for  UIC  of  the  requested  task 

parent  =  Name  of  issuing  task's  parent  task  whose  connection 
is  to  be  passed.  If  not  specified,  al]  conne:tions 
are  passed. 

bufadr  =   Address  of  buffer  to  be  given  to  the  requested  tosk 

buflen  =   Length  of  buffer  to  be  given  to  requested  task 

SC  =■•      Flags   byte: 

RP.OEX    —    (200)    Force    issuing    task    to    exit 
RP.OAL   —    (1)         Pass    all    connections    (Default    is 
none.) 


NOTE 

You  cannot  pass  all 
connections  if  the  target 
task  is  a  CLI  task. 


RP.ONX   --  (2)   Pa.ss  the  first  connection  in  the 
queue,  if  there  is  one. 
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dnam   =  ASCII  device  name  for  TI: 

unit    =   Unit  number  of  task  TI: 

task  =  RAD50  name  that  the  requc'-ed  tnsk  is  to  run  under. 
On  RSX-llM  cystems,  this  parameter  is  only  valid  if 
the  issuing  task  is  a  CLI  task. 

On  RSX-llM-PLUS  systems,  any  task  may  specify  a  new 
name  for  the  requested  task.  However,  the  requested 
(specified  in  the  tname  parameter)  task  must  be 
Installed  in  the  ...tsk  format  and  must  not  be  a  CLI 
task. 

ucbad   =  Address  of  OCB  to  pass  (CLIs  only) 

Local  Symbol  Definitions: 

R.POTK  --  RAD50  name  of  task  to  be  chained  to  (2) 

R.POUM  —  UIC  member  code  (1) 

R.POUG  --  'JIC  group  code 

R.POPT  —  Name  of  parent  whose  OCB  should  be  passed  (4) 

R.POOA  —  Address  of  OCB  to  pass  (CLIs  only)  (?) 

R.POBF  —  Address  of  command  buffer  (2) 

R.POBL  —  Length  of  command  (2) 

R.POUN  --  Unit  number  of  task  TI :   (I) 

R.POSC  —  Flags  byte  (1) 

R.PODV  —  ASCII  device  name  for  TI:   (2) 

R.POTN  —  RAD50  name  of  task  to  be  starte-l  (4) 
Macro  Expansion: 


RPOI$ 

.BYTE  11,16 

.RAD50  /tname/ 

.BLKW  3 

.BYTE  umc 

.BYTE  ugc 

.RAD50  i^tsk 

•WORD  ocbad 

.WORD  buf 

.WORD  buflen 

.ASCII  /dev/ 

.BYTE  unit 

.BYTE  sc 


tname, ,  ,  ug c,  um c, ptsk, buf, bufl en, sc, dev, unit, task , ocbad 
Die  11  DPB  SIZE  =  16.  words 
NAME  OF  TASK  TO  CHAIN  TO 
RESERVED 
UrC  MEMBER  CODE 
UIC  GROUP  CODE 

NAME  OF  TASK  WHOSE  OCB  SHOULD  BE  PASSED 
ADDRESS  OF  OCB 
ADDRESS  OF  BUFFER  TO  SEND 
LENGTH  OF  BUFFER 

ASCII  NAME  OF  TI :  OF  REQUESTED  TASK 
UNIT  NUMBER  OF  TI:  DEVICE 
PASS  BUFFER  AS  SEND  PACKET  OR  COMMAND 
CODE 


5-131 


DIRECTIVE  DESCRIPTIONS 


DSW  Return  Codes; 
lE.UPN   -- 

IE. INS   ■ 


IE. ACT 


Insufficient  dynamic  memory  to  allocate  in  offspring 
control  block,  comnand  line  buffer,  task  control 
Llock,  or  partition  v7ontrol  block. 

The  specified  task  was  not  installed,  or  It  was  a  CLI 
but  no  command  line  was  specified. 

The  specified  task  was  already  active  and  it  was  not 
a  command  line  Interpreter. 


lE.IDU  —  The  specified  virtual  terminal  unit  does  not  exist  or 
was  not  created  by  the  issuing  task. 

IE. ITS  —  A  task  that  is  not  a  CLI  specified  a  CLI  only 
parameter  or  specified  passing  all  connections  to  a 
CLI. 

lE.NVR  --  There  is  no  offspring  control  block  from  the 
specified  parent  task. 

lE.ALG  --  A  CLI  specified  a  parent  name  and  an  offspring 
control  block  address  that  did  not  describe  the  same 
connection,  or  either  a  parent  name  or  an  offspring 
control  block  address  was  specif!  :'>.l  and  the  pass  all 
connections  flcg  or  the  pass  next  connection  flag  was 
set . 

lE.PNS  —  The  task  control  block  cannot  be  created  in  the  same 
partition  as  its  prototype. 


lE.ADP   -- 


IE. SOP 


Part  of  the  DPB,  exit  status  blpck,  or   command   line 
is  out  of  the  Issuing  task's  address  space. 

Die  or  DPB  size  is  invalid. 
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RQST$ 


5.3.54   Request  Task 

The  Request  Task  directive  instructs  the  system  to  activate  a  task. 
The  task  is  activated  and  subsequently  runs  contingent  upon  priority 
and  memory  availability.  The  Request  Task  directive  is  the  basic 
mechanism  used  by  running  tasks  to  initiate  other  installed  (dormant) 
tasks.  The  Request  Task  directive  is  a  frequently  uned  subset  of  the 
Run  directive.   See  Notes  below. 

FORTRAN  Call  : 

CALL  REQUES  ( tak , (opt ] [ , ids] ) 

tsk   «   Task  name 

opt      =      A    4-word    integer    array 

optd) 


opt(2) 

opt(3) 
opt (4) 


Partirion   name      first      half; 
must   be   present 

Partition   name   second      half,- 
must    be    present 


ignored,      but 
ignored,      but 


Priority;      ignored,    but   must   be   present 
User    Identification   Code 


ids 
Macro   Call; 
RQSTS 


Directive   status 


tsk, [prt] , [pri]  [  ,ugc,umc] 
tsk      =      Task    name 

prt      =      Partition   name;       ignored,    but    must    be    present 
P-i      =      Priority;      ignored,    but   must    be   present 
ugc      =      iirc   group   code 
umc      =      UIC   membei'   code 
Macro    Expansion: 


RQSTS  ALPHA, , ,20, 10 

.BYTE  11. ,7 

.RAD50  /ALPHA/ 

.WORD  0,0 

.WORD  0 

.BYTE  10,20 


;RQSTS    MACRO    DIC,    DPB    SIZE=7    WORDS 

;TASK    "ALPHA" 

; PARTITION  IGNORED 

;r?IORITY    IGNOi^ED 

;UIC    UNDER   WHICH   TO    RUN    TASK 
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Local    Symbol  Definitions: 

R.QSTN  —     Task   name    (4) 

R.QSPN  —      Partition    name    (4) 

R.QSPR  —      Priority    (2) 

R.QSGC  —      UIC   group    (1) 

R.QSPC  —      UIC   member    (1) 
DSW   Return   Codes: 

IS. sue  —      Successful    completion. 

lE.UPN  —      Insufficient   Jynamic   memory. 

lii.INr  —      Task    is   not    installed. 

IE. ACT  —      Task    is    already   active. 

lE.ADP      —      Part   of    the    DPB    is   out   of    the    Issuing    task'j      address 
space . 

lE.SDP      —      Die   or    DPB   size    is    invalid. 

Notes : 

1.  The  requested  task  must  be  Installed  in  the  system. 

2.  If  the  partition  in  which  a  requested  task  is  to  run  is 
already  occupied,  the  Executive  places  the  task  in  a  queue  of 
tasks  waiting  for  that  partition.  The  requested  task  then 
runs,  depending  on  priority,  and  resource  availability,  when 
the  partition  is  free.  Another  possibility  Is  that 
checkpointing  may  occur.  If  the  current  occupant(s)  of  the 
partition  is  checkpointable,  has  checkpointing  enabled,  and 
is  of  lower  priority  than  the  requested  task.  It  Is  written 
to  disk  when  Its  current  outstanding  I/O  completes;  the 
requested  task  is  then  read  into  the  partition. 

3.  Successful  completion  means  chat  the  task  has  been  declared 
active,  not  that  the  task  Is  actually  running. 

4.  The  requested  task  acquires  the  same  TT:  terminal  assignment 
as  that  of  the  requesting  lisk. 

5.  The  requested  task  always  runs  at  the  priority  specified  In 
its  task  header. 

6.  A  task  that  executes  in  a  system-controlled  partition 
requires  dynamic  memory  for  the  partition  control  block  used 
to  describe  its  memory  requirements. 
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7.  In  a  system  that  does  not  sjv.^ort  multiuser  protection,  a 
task  can  be  requested  under  any  UIC,  regardless  of  the  UIC  of 
the  requesting  task.  If  no  UIC  Is  specified  in  the  request, 
the  system  uses  the  UIC  from  the  task's  header,  which  was 
spe'  '.fled  at  task-build  time. 

8.  In  a  system  that  supports  multiuser  protection,  each  active 
task  has  two  UICs:  a  protection  UIC  and  a  default  UIC. 
These  are  both  returned  when  a  task  issues  a  Get  Task 
Parameters  directive  (GTSKS)  .  The  UICs  are  used  in  the 
following  ways : 

•  The  protection  UIC  determines  the  task's  access  rights  for 
opening  files  and  attaching  to  regions.  Wnen  a  task 
attempts  to  open  a  file,  the  system  compares  the  task's 
protection  UIC  against  the  protection  mask  of  the 
specified  UFD;  the  compariijon  determines  whether  the  task 
Is  to  be  considered  for  system,  owner,  grojp,  or  world 
access . 

•  The  default  UIC  is  used  by  the  File  Control  Subroutines 
(PCS)  to  determine  the  default  UFD  when  c  file-open 
operation  does  not  specify  a  UIC.  (The  defa'jlt  UIC  has  no 
significance  when  a  task  attaches  to  a  region.) 

In  a  multiuser  protection  system,  each  terminal  also  has  a 
protection  UIC  and  a  default  UIC.  If  a  terminal  is 
nonpr Ivlleged ,  the  protection  UIC  is  the  log-on  UIC,  and  the 
default  UIC  is  the  UIC  specified  In  the  last  SET  /UIC  command 
issued.  If  no  SET  /UIC  command  has  been  Issued,  the  default 
UIC  is  equal  to  the  log-on  UIC.  If  the  terminal  Is 
privileged,  both  the  protection  and  the  default  UICs  are 
equal  either  to  the  UIC  specified  in  the  last  SET  /UIC 
command  or  to  the  log-on  UIC  if  a  SET  /UIC  comioand  has  not 
b<>en  issued  . 

The  system  establishes  a  task's  UICs  when  the  task  Is 
activated.  In  general,  when  the  MCR  Dispatcher  or  the  MCR 
F«un  command  activates  a  task,  the  task  assumes  the  protection 
and  default  UICs  of  the  Issuing  terminal.  However,  if  the 
user  specifies  the  /UIC  keyword  to  the  MCR  or  DCL  Install  or 
Run  command,  the  specified  UIC  becomes  the  dr»fault;  UIC  for 
the  activated  task;  and  if  the  issuing  terminal  is 
privileged,  the  specified  UIC  becomes  the  activated  task's 
protection  UIC  as  well. 

The  system  establishes  UICs  in  the  same  manner  when  one  task 
issues  a  Request  directive  to  activate  another  task.  The 
protection  and  default  UICs  of  the  Issuing  task  generally 
become  the  corresponding  UICs  of  the  requested  task. 
However,  if  a  nonpr iv lleged  task  specifies  a  UIC  in  a  Request 
directive,  the  specified  UIC  becomes  only  the  default  UIC  for 
the  requested  task.  If  a  privileged  task  specifies  a  UIC  In 
a  Request  directive,  the  specified  UIC  becomes  both  the 
protection  and  default  UIC  for  the  requested  task. 


5-135 


DIRECTIVE  DESCRIPTIONS 

RREF$ 

5.3.55  Receive  By  Reierence 

The  Receive  By  r'.eference  directive  requests  the  Executive  to  dequeue 
the  next  packet  in  the  receive-by-ief erence  queue  of  the  issuing 
(receiver)  task.  Optionally,  the  task  will  exit  if  there  are  no 
packets  in  the  queue.  The  directive  may  also  specify  that  the 
Executive  proceed  to  map  the  region  referred  to. 

If  successful,  the  directive  declares  a  significant  event. 

Sach  reference  in  the  task's  receive-by-ref erence  queue  represents  a 
separate  attachment  to  a  region.  If  a  task  has  multiple  references  to 
a  given  region,  it  is  attached  to  that  region  the  corresponding  number 
of  timt>s.  Because  region  attachment  requires  system  dynamic  memory, 
the  receiver  task  should  detach  from  any  region  that  it  was  already 
attached  to  in  or'er  to  prevent  depletion  of  the  memory  pool.  That 
is,  the  task  needs  to  be  attached  to  a  given  region  only  once. 

If  the  Executive  does  not  find  a  packet  in  the  queue,  and  the  task  has 
set  WS.RCX  in  the  window  status  word  (W.NSTS),  the  task  exits.  If 
WS.RCX  is  not  set,  the  Executive  returns  the  DSW  code  IE. ITS. 

If  th-^  Executive  finds  a  packet,  it  writes  the  information  provided  to 
the  corresponding  words  in  the  Window  Definition  Block.  This 
information  provides  sufficient  information  to  map  the  reference, 
according  to  the  sender  task's  specifications,  with  a  previously 
created  address  window. 

If  the  address  of  a  10-word  receive  buffer  nas  been  specified  (W.NSRB 
in  the  Window  Definition  Block),  then  the  sender  task  name  and  the 
eight  additional  words  passed  by  the  sender  task  (if  any)  are  placed 
in  the  specified  buffer.  If  the  sender  task  did  not  pass  on  any 
additional  information,  the  Executive  writes  in  the  sender  task  name 
and  eight  words  of  zero. 

If  the  W3.MAP  bit  in  the  window  status  word  has  been  sec  to  1,  the 
Executive  transfers  control  to  the  Map  Address  Window  directive  (see 
Section  6.3.4C)  to  attempt  to  map  the  reference. 

When  a  task  that  has  unreceived  packets  in  its  receive-by-ref erence 
queue  exits  or  is  removed,  the  Executive  removes  the  packets  from  the 
queue  and  deallocates  them.   Any  related  flags  are  not  set. 

FORTRAN  Call  : 

CALL  RREF  ( i wdb , [ isrb]  [ ,  ids] ) 

iwdb  =  An  8-word  integer  array  containing  a  Window  Definition 
Block  (see  Section  3.5.2.2) 

isrb  =  A  10-word  integer  array  to  be  used  as  the  receive 
buffer.  If  the  call  omits  this  parameter,  the 
contents  of  iwdb(8)  are  unchanged. 

ids    =   Directive  status 

Macro  Call : 

RREF$  wdb 

wdb  =  Window  Definition  Block  address 
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Macro  Expansion: 

RREF$     WDBADR 
.BYTE     81. ,2 
.WORD     WDBADR 

Window  Definition  Block 

Input  parameters: 

Array    Offset  . 
Element 

iwdb(l) 

bits  0-7   W.NID 

iwdb(7)    W.NSTS   - 


;RREF$  MACRO  DIG,  DPB  SIZE^.:  WORuS 
;WDB  ADDRESS 

Parameters: 


iwdb(8)    W.NSRB  — 

Output  parameters: 

lwbd(4)    W.NRID  — 

iwdb(5)   W.NOFF  — 

iwdb(6)    W.NLEN  — 

iwdb(7)    W.NSTS  — 


ID  of  an  existing  window  if  region  is  to  bo 
mapped 

Bit  settings-'^  in  the  window  status  word: 

Bit  Definition 

WS.MAP      1  if  received  reference   is   to 
be  mapped 

WS.RCX      1  if  task  exit  desired  when   no 
packet  is  found  in  the  queue 

Optional  address  of  a  10-word  buffer,  to 
contain  the  sender  task  name  and  additional 
information 


Region    ID     (pointer 
description) 


to 


attachment 


Offset  word  specified  by  sender  task 

Length  word  specified  by  sender  task 

Bit  settings!  in  the  window  status  word: 

Bit  Definition 

WS.RED      1  if  attached  with  read  access 

WS.WRT      1  if  attached  with  write  access 

WS.EXT      1   if   attached    with   extend 
access 

WS.DEL      1   if   attached    with   delete 
access 

WS.RRF      1  if  receive  was  successful 

The  Executive  clears  the  remaining  bits. 


1.  If  you   are   a   FORTRAN   programmer,   refer   to   Section   3.5.2   to 
determine  the  bit  values  represented  by  the  symbolic  names  described. 
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Local  Symbol  Definitions: 

R.REBA   —  Window  definition  block  address  (2) 
DSW  Return  Codes: 

IS. sue   —  Successful  completion. 

IS.HWR   —  Region  has  incurred  a  parity  error, 

IE. ITS   —  Mo  packet  found  in  the  receive-by-ref erence  queue. 

lE.ADP   —   Address  check  of  the  DPB ,  WDB ,  or  the  receive  buffer 
(W.NSR3)  failed. 

lE.SDP   --   DIG  or  DPB  size  is  invalid. 
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RSUM$ 

5.3.56   Resume  Task 

The  Resume  Task  directive  Instructs  the  system  to  resume  the  execution 
of  a  task  that  has  issued  a  Suspend  directive. 

FORTRAN  Call: 

CALL  RESUME  (tsk[ ,ids] ) 

tsk   =   Task  name 

ids   =  Directive  status 

Macro  Call  : 

RSUM$    tsk 

tsk   =  Task  name 

Macro  Expansion: 

R&UMS    ALPHA 

.BYTE     47., 3  ;RSUM$  MACRO  DIC,  DPB  SIZE=3  WORDS 

.RAD50    /ALPHA/  ;TASK  "ALPHA" 

Local  Symbol  Definitions: 

R.SUTN  --   Task  name  (4) 
DSW  Return  Codes: 

IS. sue  —   Successful  completion. 

IE. INS  —   Task  is  not  installed. 

IE. ACT  —   Task  is  not  active. 

IE. ITS  —   Task  is  not  suspended. 

lE.ADP   --   Part  of  the  Drs  is  out  of  tht  issuing  task's  address 
space . 

lE.SDP   —   Die  or  DPB  size  is  invalid. 
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RUN$ 

5. 3. 57   Run  Task 

The  Run  Task  directive  causes  a  task  to  be  requested  at  a  specified 
future  time,  and  optionally  to  be  requested  periodically.  The 
schedule  time  is  specified  in  terms  of  delta  time  from  issuance.  If 
the  smg,  rmg,  and  rnt  parameters  are  omitted,  Run  is  the  same  as 
Request  except  that: 

1.  Run  causes  the  task  to  become  active  one  clock  tick  after  the 
directive  is  issued. 

2.  The  system  always  sets  the   TI:    device   for   the   requested 

task ,  to  CO: . 

See  Notes  below. 
FORTRAN  Call : 

CALL  RUN  (tsk, [opt] , [smg] ,snt, [rmg] , [rnt] [,ids] ) 
tsk  =     Task  name 
opt   =   A  4-word  integer  array 

opt(l)   =  Partition  name   first   half;    ignored,   but 
must  be  present 

opt(2)  -=      Partition   name    second    half;     ignored, 
but  must  be  present 

opt{3)   =   Priority;   ignored,  but  must  be  present 

opt(4)   =   User  Identification  Code 
smg   =   Schedule  delta  magnitude 

snt   =   Schedule  delta  unit  (either  1,  2,  3,  or  4) 
rmg   =   Reschedule  interval  magnitude 
rnt   =   Reschedule  interval  unit 
Ids   =   Directive  status 
The  ISA  standard  call  for  initiating  a  task  is  also  provided: 
CALL  START(tsk,smg,snt[ , ids] ) 
tsk   =   Task  name 
smg   =   Schedule  delta  magnitude 

snt   =   Schedule  delta  unit  (either  0,  1,  2,  3,  or  4) 
ids   =  Directive  status 
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Macro  Call ; 

RUNS    tsk, [prt] , (pri) , [ugc] , [umc] , [smg] ,3nt [ , rmg , rnt] 

tsk  =   Task  name 

prt  =   Partition  name;   ignored,  but  must  be  present 

pr  I  =   Priority;   i-jnored,  but  must  be  present 

ugc  ■=   UIC  group  code 

umc  =   UIC  member  code 

smg  =   Schedule  delta  magnitude 

snt  =   Schedule  delta  unit  (either  1,  2,  3,  or  4) 

rmq  =   Reschedule  Interval  magnitude 

rnt  =   Reschedule  interval  unit 


Macro  Expansion. 


RUNS 

BYTE 

.RAD50 

.WORD 

.WORD 

.BYTE 

.WORD 

.WORD 

.WORD 

.WORD 


ALPHA, ,,20,10, 20. ,3, 10. , 3 


17.  ,  IL 

/ALPHA/ 

0,0 

0 

10,  20 

23. 

3 

10. 

3 


RUNS  MACRO  Die,  DPB  SIZE-11.   WORDS 

TASK  "ALPHA" 

PARTITION    IGNORED 

PRIOr^ITY    IGNORED 

UIC    TO    RUN    TASK    UNDER 

SCHEDULE    MAGNITUDE=»20 

SCH.     DELTA    TIME    l)NIT=MINUTE     (-3) 

RESCH.     INTERVAL   MAGN ITUDE»1 0 . 

RESCH.     INTERVAL    UNIT»MINUTE     (-3) 


Local    Symbol  Oo£i nit  ions: 

R.UNTN  --  Task    name    (4) 

K.UNPN  —  Partition    name    (4) 

R.UNPR  --  Priority    (2) 

R.UNGC  --  UIC   group  code    (1) 

R.UNPC  —  UIC   member    code    (1' 

R.UNSM  --  Schedule   magnitude    (2) 

R.UNSU  —  Schedule    unit    (2) 

R.UNRM  —  Reschedule   magnitude    (2) 

R.UNRU  --  Reschedule    unit    (2) 
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DSW    Return    Codes: 

tor    CALL   RUN   and    RUNS: 

IS. sue        —    Successful    completion. 

TE.UPN        --    Insufficient   dynamic   memory. 

IE. ACT        --   Multiuser    task   name    specified. 

IE. INS        --    Task    is   not    installed. 

lE.PRI         --   Nonpr tvileqed    task   specified    a    UIC  other    than    its 
own  . 

IE. ITI         --    Invalid    tlm^    parameter. 

lE.ADP         --    Part      of    the      DPB    is      out      of    the       issuinq       task's 
address    spsce. 

lE.SDP        --   Die   or    DPB   size    is    Invalid. 

For    CALL    START: 

RSX-1 IM/M-PLUS    provides    the    followfnq    positive    error    codes      to 
be    returned    for    ISA  calls: 

2  —      Insufficient   dynamic    storage. 

3  —      Specified    task   not    installed. 
W  —      Invalid    time    parameter. 

98  —      Invalid    event    flag    number. 

99  --      Part   of    DPB    Is   out    of    task's   address    space. 

100  --      Die   or    DPB   size    is    invalid. 


Notes 


In  a  multius'^r  protection  system,  a  nonpr  iv  11  eged  task  cannot 
specify  a  UIC  that  is  not  equal  to  its  own  protection  UIC. 
(See      Note      a,       Section      5."?. 54,      for      a      definition      of  ,e 

protection    UIC.)    A   privileged    task   can    specify  any   UIC. 

In  a  system  that  does  not  support  multiuser  protection,  a 
task  may  be  run  under  ?tny  UIC,  regardless  of  the  UIC  of  the 
requesting  task.  it"  no  I'lC  is  specified  in  the  request,  the 
Executive  uses  the  default  UIC  from  tho  requested  task's 
header.  The  priority  is  always  that  specifieJ  in  the 
requested    task's    Task    Control    Block. 
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3.  The  target  task  must  be  Installed  In  the  system. 

4.  IE  there  is  not  enough  room  In  the  partition  In  which  a 
requested  task  is  to  run,  the  Executive  places  the  task  in  a 
queue  of  tasks  waiting  for  that  partition.  The  requested 
task  wi:i  then  run,  depending  on  priority  and  resource 
availability,  whe.i  the  partition  is  free.  Another 
possibility  is  that  checkpointing  will  occur.  If  the  current 
occupant(s)  of  the  partition  is  checkpointable,  has 
checkpointing  enabled,  is  of  lower  priority  than  the 
requested  task,  or  is  stopped  for  terminal  input,  it  will  be 
written  to  disk  when  its  current  outstanding  I/O  completes. 
The  requested  task  will  then  be  read  into  the  partition. 

5.  Successful  completion  means  the  task  has  been  made  active; 
it  does  not  mean  that  the  task  is  actually  running. 

6.  Time  Intervals 

The  Executive  returns  the  code   lE.ITI  in   the   DSW  if   the 

directive   specifies   an   invalid   time  parameter.  A   time 

parameter  consists  of  two  components:  the  time  interval 
magnitude,  and  the  time  interval  unit. 

A  legal  magnitude  value  (smg  or  rmq)  is  related  to  the  value 
assigned  to  the  time  interval  unit  snt  or  rnt.  The  unit 
values  are  encoded  as  follows: 

For  an  ISA  FORTRAN  call  (CALL  START): 

0  =  Ticks  --  A  tick  occurs  for  each  clock  interrupt  and 

is  dependent  on  the  type  of  clock  installed  in  the 
system. 

For  a  line  frequency  clock,  the  tick  rate  is  either 
50  or  60  per  second,  corresponding  to  the  power-line 
frequency. 

For  a  programmable  clock,  a  maximum  of  1000  ticks 
per  second  is  available  (the  exact  rate  is 
determined  during  system  generation). 

1  =  Milliseconds   --   The    subroutine   converts    the 

specified  magnitude  to  the  equivalent  number  of 
system  clock  ticks. 

For  all  other  FORTRAN  and  all  macro  calls: 

1  =   Ticks  --  See  definition  of  ticks  above. 
For  both  types  of  FORTRAN  calls  and  all  iracro  calls: 

2  =   Seconds 

3  =  Minutes 

4  =   Hours 
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The  magnitude  is  the  number  of  units  to  be  clocked.  The 
following  list  describes  the  magnitude  values  that  are  valid 
for  each  type  of  unit.  In  no  case  can  the  magnitude  exceed 
24  hours.   The  list  applies  to  both  FORTRAN  and  macro  calls. 

If  unit  =  0,  1,  oi  2,  the  magnitude  can   be   any   positive 
value  with  a  maximum  of  15  bits. 

If  unit  =  3,  the  magnitude  can  have   a   maximum   value   of 
1440(10)  . 

If  unit  =  4,  the  magnitude  can  have   a   maximum   value   of 
24(10)  . 

7.  The  schedule  delta  time  is  the  difference  in  time  from  the 
issuance  of  the  RUN$  directive  to  the  time  the  task  is  to  b^ 
r  'p  This  time  may  be  specified  in  the  range  from  one  clock 
tick  to  24  hours. 

8.  The  reschedule  interval  is  the  difference  in  time  from  task 
initiation  to  the  time  the  task  is  to  be  reinitiated.  If 
this  time  '.nterval  elapses  and  the  task  is  still  active,  no 
reinitiation  request  will  be  Issued.  However,  a  new 
reschedule  Interval  will  be  started.  The  Executive  will 
continually  try  to  start  a  task,  wait  for  the  specified  time 
interval,  and  then  restart  the  task.  This  process  continues 
until  a  CSRQS  (Cancel  Time  Based  Initiation  Requests) 
directive  or  an  MCR  or  DCL  Cancel  command  is  issued. 

9.  Run  requires  dynamic  memory  for  the  clock  queue  entry  used  to 
start  the  task  after  the  specified  delta  time.  If  the  task 
is  to  run  in  a  system-controlled  partition,  further  dynamic 
memory  is  required  for  the  task's  dynamically  allocated 
partition  control  block  (PCB)  . 

10.   If  optional  rescheduling  is  not  desired,  then  the  macro   call 
should  omit  the  arguments  rmg  and  rnt. 
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5.3.58   Specify  Command  Arrival  AST 

This  directive  instructs  the  system  to  enable  or  disable  command 
arrival  ASTs  for  the  issuing  CLI  task.  If  command  arrival  ASTs  are 
enabled,  the  executive  transfers  control  to  a  specified  address  when 
commands  have  been  queued  to  the  CLI. 

Only  CLI  tasks  can  use  this  AST. 

The  format  of  the  stack  when  the  AST  routine  is  entered  is  as  follows: 

SP+10  -  zero  since  no  event  flags  are  involved 

SP+06  -  PS  of  task  prior  to  AST 

SP+04  -  PC  of  task  prior  to  AST 

SP+02  -  DSW  of  task  prior  to  AST 

SP+00  -  address  of  command  buffer  just  queued 

The  AST  routine  must  remove  the  command  buffer  address  from  the  stack 
before  issuing  an  ASTX$  directive. 

The  command  buffer  address  may  be  used  when  issuing  a  GCCI$  directive. 

FORTRAN  Call : 

Not  supported. 
Macro  Call: 

SCAAS   [ast] 

ast  =  AST  service  routine  entry  point.  Omitting  this 
parameter  disables  command  arrival  ASTs  for  the 
issuing  task  until  the  directive  is  respecified. 

Macro  Expansion: 

SCAA$    ast 

.BYTE    173., 2  ;DIC  =  173  ,  DPB  SIZE  =  2  WORDS 

.WORD    ast  ;ADDRE3S  OF  AST  ROUTINE 

Local  Symbol  Definitions: 

S.CAAE   —   Address  of  AST  routine 
DSW  Return  Codes: 

IE. ITS   —   ASTs  are  already  not  desired. 

IE. AST   —   Directive  issued  from  AST  state. 

lE.PRV   —   Issuing  task  is  not  a  CLI. 

lE.UPN   --   Insufficient  dynamic  memory. 

lE.ADP   —   Part  of  the  DPB  was  out  of  the  Issuing  task's  address 
space . 

lE.SDP   —   Die  or  DPB  size  is  invalid. 
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5.3.59   Supervisor  Call  ($S  Form  Recommended) 

The  Supervisor  Call  directive  is  Issued  by  a  task  in  user  mode  or 
supervisor  mode  to  call  a  supervisor-mode  library  routine.  Returning 
to  the  user  mode  from  supervisor  mode  routines  entered  with  the  SCAL$S 
directive  (Macro  form)  is  effected  by  a  completion  routine  that  i.s 
executed  in  supervisor  mode.  Note  that  only  the  $S  form  is  available 
for  this  directive. 

NOTE 

We  strongly  suggest  using  the 
taskbuilder  to  resolve  references  to 
supervisor  mode  routines  rather  than 
explicitly  using  the  SCAL$S  directive. 
Doing  so  allows  you  to  take  advantage  of 
any  new  techniques  implemented  in  future 
releases  automatically. 

FORTRAN  Call: 

Not  Supported 
Mf.cro  Call: 

SCAL$S   saddr,caddr 

saddr  =  Address  of  the  called  supervisor-mode  routin* 

caddr   -  Address  of  the  completion  routine  for  return   to   the 
cal ler 

•rr    =  Address  of  error  routine 

Macro  Expansion: 

SCALSS  JRAD, CHAD, ERR 

MOV  CRAD,-(SP) 

MOV  SRAD,-(SP) 

MOV  (PC)+,-(SP) 

.BYTE  155. ,3 

EMT  "0<377> 

BCC  .+6 

CALL  ERR 

Local  Symbol  Definitions: 

None 
DSW  Return  Codes: 

IS. sue   —   Successful  completion. 

lE.ADP      —      Part  of   the   DPS   is   out   of    the    issuing    task's      address 
space.  

IE. SOP      —      Die   or    DPB    size    is    Invalid. 
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Note: 


This  directive  transfers  control  to  the  specified  routine  in 
supervisor  mode  with  all  registers  preserved  and  with  the 
following  stack: 


Supervisor  stack  pointer 


Completion  routine  address 


PC+2  of  Supervisor  Call 


PS  of  Supervisor  Call 


User  stack  pointer 

The  stack,  as  shown,  represents  the  stack  content  Immediately 
after  Issuing  the  Supervisor  Call  directive.  The  user  stack 
pointer  is  not  guaranteed  to  remain  valid. 

The  supervisor  stack  is  the  user  stack  with  three  words  pushed 
onto  it.  It  is  mapped  in  Supervisor  Data  Space  along  with  the 
rebt  of  the  user  mode  mapping.  Previous  mode  bits  are  set  to  the 
caller's  mode.  This  is  normally  user  mode,  but  It  may  be 
supervisor  mode. 

If  there  is  insufficient  stack  spacf  for  the  three  words,  the 
issuing  task  is  aborted. 


5-147 


DIRECTIVE  DESCRIPTIONS 


SCLI$ 


5.3.60   Set  Command  Line  Interpreter 

The  Set  Command  Line  Interpreter  directive  instructs  the  system  to  set 
up  the  specified  CLI  as  the  CLI  for  the  indicated  terminal.  The 
issuing  task  must  be  privileged  or  j  CLI. 

If  the  restricted  access  flag  (CP.RST)  in  the  CLI  status  word  is  set, 
the  issuing  CLI  task  is  the  only  CLI  task  that  can  set  a  terminal  to 
that  CLI. 

FORTRAN  Call : 

CALL  SETCLI  ( ic 1 i , i dev , i un 1 1 [ , Ids] ) 

icli    =   Name  of  a  twc-word  array  element  containing  the   name 
of  the  CLI  the  terminal  is  to  be  set  to 

Idev    =   Name  of  an  integer  containing  the  ASCII  name   of   the 
terminal  to  be  set  (default  -  TI:) 

iunit   =   Name  of  an  integer   containing   the   unit   number   of 
terminal 

id«    =   Directive  status 
Macro  Cal 1 : 

SCLIS  cli , [dev] , [unit] 

cli  =   Name  of  the  CLI  the  terminal  is  to  be  set  to 

dev  =   ASCII  name  of  the  terminal  to  be  set  (default  =  TI:) 

unit  =   Unit  number  of  terminal 

Local  Symbol  Definitions: 

S.CIDV  —   ASCII  name  of  the  terminal  whose  CLI  is  to  be  set 

S.CIUN  --   Octal  unit  number  of  terminal 

S.CICN   --   RAD50  name  of  the  CL.  that  the  terminal  Is  to  be   set 
to 

Macro  Expansion: 

SCLIS  cli, dev, unit 

.BYTE  173., 5  ;DIC    173.     DPB    SIZE    -    5    WORDS 

.RAD50  /cli/  ;CLI    NAME 

.ASCII  /dev/  ;ASCII    NAME    OF    TERMINAL    TO    BE    SET 

.WORD  unit  ;UNIT    NUMBER 
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DSW  Returns; 


lE.PRI      —      Task   not    privileged    or    not    a   CLI.       If    CP.RST   was    set, 

task    was   not    the    CI  I    ii-self. 

IF.IDU      --      Device    not    a    terminal    or   does   not    exlit. 

IE. INS      --      Specified    CLI    does    not    exist. 

lE.UPN      --      Insufficient    dynamic   memory. 

lE.ADP      --      p.-^rt    of    the    DPB   was   out    of    the    issuing    task's   address 
space . 

lE.SDP      --      Die   or    DPfa    length    is    invalid. 


• 
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SDAT$ 

5.3.61      Send    Data 

The  Send  Data  directive  Instiructs  the  system  to  declare  a  significant 
event  and  to  queue  (FIFO)  a  13-word  block  of  data  for  a  task  to 
receive. 


NOTE 

When  a  local  event  flag  is  specified, 
the  indicated  event  flag  is  set  for  the 
sending  task;  a  significant  event  is 
always  declared. 


FORTRAN  Call : 

CALL  SEND  ( tsk  ,buf , [ ef n]  [ , ids] ) 

tsk   =   Task  name 

buf   =   13-word  integer  array  of  data  to  be  sent 

efn   =   Event  flag  number 

ids   =   Directive  status 
Macro  Call : 

SDATS     tsk, buf [, efn] 

tsk   =   Task  name 

buf      =     Address  of    13-word   data   buff    - 

efn      =      Event    flag    number 

Macro    Expansion: 

aPHA,DATBUF,  52. 

SDATS    MACRO    DIC,    DPB    SIZE=5    WORDS 
RECEIVER    TASK   NAME 
ADDRESS    OF    13. -WORD    BUFFER 
EVENT    FLAG    NUMBER    52. 

Local    Symbol  Definitions: 

S.DATN  —      Task   name    (4) 

S.DABA  --      Buffer    address    (2) 

S.DAEF  —      Event    flag    number    (2) 


SDATS 

ALPHA, D 

.BYTE 

71. ,5 

.RAD50 

/ALPHA/ 

.WORD 

DATBUF 

.WORD 

52. 
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D/jW  Return  Codes: 

IS. sue   —  Successful  completion. 

Receiver  task  is  not  installed. 
Isufficient  dynamic  memory. 


IE. INS 
lE.UPN 
lE.IEF 


lE.ADP      — 


lE.SDP 


Invalid  event  flag  number  (EFN<0,  or  EFN>96  if  group 
global  event  flags  exist  for  the  task's  group;  or 
EFN>64    if    not) . 

Part  of  the  DPB  or  data  block  is  out  of  the  issuing 
task's   address    space. 

DIG   or    DPB    size    is    Invalid. 


Notes ; 


1.  Send  Data  requires  dynamic  memory. 

2.  If  the  directive  specifies  a  local  event  flag,  the  flag  is 
local  to  the  sender  (Issulngj  task.  RSX-llV  does  not  allow 
one  task  to  set  or  :lear  a  flag  that  Is  local  to  another 
t  a  r  k  . 

Normally,  the  event  flag  Is  used  to  trigger  the  receiver  task 
Into  some  action.  For  this  purpose,  the  event  flag  must  be 
common  (33  through  64)  or  group  global  (65  through  96)  rather 
than  local.  (Refer  to  the  descriptions  of  the  Receive  Data 
directive  and  the  Exit  IF  directive.) 

3.  In  RSX-llM-PLUS  systems  the  Send  Data  directive  is  treated  as 
a  13-word  Variable  Send  Data  directive  (see  Section  5.3.90). 
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5.3.62   Send,  Request  and  Connect 

The  Send,  Request  And  Connect  directive  performs  a  Send  Data  to  the 
specified  task.  Requests  the  task  if  it  is  not  already  active,  and 
then  Connects  to  the  task.  The  receiver  task  normally  returns  status 
by  an  Emit  Status  or  Px i t  With  Status  directive. 

FORTRAN  Call : 

CALL  SDRC  (rtnair.e,  i'ouf  ,  r  iefn]  ,[  last]  ,[  iesb]  ,[  iparm]  (,  ids)  ) 

rtname   =   Target   task   name   of   the   offspring   task   to   be 
connected 

Ibuf    =   Name  of  l.^-word  send  buffer 

iefn     =   Event  flag  to  be  set  when  the  offspring   task   exits 
or  emits  status 

last     =   Name  of  30      AST   routine   to   be   called   when   the 
offspring  task  exits  or  emits  status 

iesb    =   Name  of  an   8-word  status  block  to   be   written   when 
the  offspring  task  exits  or  emits  status 

Word    0  —  Offspring  task  exit  status 

Word     1  --  TKTN  abort  code 

Word   2-7  --  Reserved 

NOTE 

The  exit  status  block  defaults  to  1  one 
word.  To  use  the  8-word  exit  status  block, 
you  must  specify  the  logical  or  of  the 
symbol  SP.WXB  and  the  event  flag  number  in 
th''  iefn  parameter  above. 


iparm    =   Name  of  a  word  to  receive  the  status   block   address 
when  an  AST  occurs 

ids      =   Integer  to  receive  the  Directive  Status  Word 

Macro  Call: 

SDRCS     tn3me,buf , [efn] , [east] , [esb] 

tname    =   Target   task   name   of   the   offspring   task   to   be 
connec-ed 

buf      =   Address  of  13-WGrd  send  buffer 

•fn      =   The  event  flag  to  be  cleared   on   issuance   and   set 
when  the  offspring  task  exits  or  emits  status 

east     =   Address  of  an  AST  routine   to   be   called   when   the 
offspri^g  task  exits  or  emits  status 
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Address  of  an  8-word  status  block  to  be  written  when 
the  offspring  task  exits  or  emits  status 

Word   0   —  Offspring  task  exit  status 

Word   1   --  TKTN  abort  code 

Word  2-7  --  Reserved 


NOTE 

The  exit  status  block  defaults  to  1  one 
word.  To  use  the  8-word  exit  status  block, 
you  must  specify  the  logical  or  of  the 
symbol  SP.WXB  and  the  event  flag  number  in 
the    efn    paiameter    above. 


Macro    Expansion: 


SDRC$ 

ALPHA, 

.BYTE 

141. ,7 

.RAD50 

ALPHA 

.WORD 

BUFFR 

.BYTE 

2 

.BYTE 

16. 

.WORD 

SDRCTR 

.WORD 

STBLK 

ALPHA, BUFFR, 2, SDRCTR, STB LK 

SDRCS    MACRO    DIG,     DPB    SIZE=7    WORDS 

TARGET    TASK    NAME 

SEND    BUFFER    ADDRESS 

EVENT    FLAG    NUMBER    =    2 

EXIT    STATUS    BLOCK    CONSTANT 

ADDRESS  OF  AST  ROUTINE 

ADDhESS  of  STATUS  BLOCK 

Local  Symbol  Definitions: 

S.DRTN  —   Task  name  (4) 

S.DRBF  --   Buffer  address  (2^ 

S.DREF  —   Event  flag  (2) 

S.DREA  —   AST  routine  address  (2) 

S.DRES  —   Status  block  address  (2) 
DSW  Return  Codes: 

IS. sue  —   Successful  completion. 

lE.UPN  —  Insufficient  dynamic  memory  to  allocate  a  send 
packet,  Offspring  Control  Block,  Task  Control  Block, 
or  Partition  Control  Block. 

IE. INS  --  The  specified  task  is  an  ACP  or  has  the  no-send 
attr  ibute . 

lE.IEF  —  An  invalid  event  flag  number  was  specified  (EFN  <  0 
or  EFN  >  96  if  group  global  event  flags  exist  for  the 
task.   EFN  >  64  i  f  not.)  . 

lE.ADP  —  Part  of  the  DPB  or  exit  status  block  Is  not  In  the 
issuing  task's  address  space. 

lE.SDP   --   Die  or  DPB  size  is  invalid. 
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Notes ; 


1.  If  the  specified  event  flag  Is  group  global,  the  use  count 
for  the  event  flag's  group  i;  incremented  to  prevent 
premature  elimination  of  the  event  flags.  The  use  count  is 
run  down  when: 

•  Status  is  returned  from  the  connected  task. 

•  The  Issuing  task  exits  before  status  is  returned. 

2.  The  virtual  mapping  of  the  exit  status  block  should  not  be 
changed  while  the  connection  Is  in  effect.  Doing  so  may 
result  in  obscure  errors. 

3.  If  the  directive  Is  rej<icted,  the  state  of  the  specified 
event  flag  is  indeterminate. 
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5.3.63   Send  Data  Request  and  Pass  Offspring  Control  Block 

This  directive  instructs  the  system  to  send  a  send  data  packet  for  the 
specified  task,  chain  to  the  requested  t<isk,  and  request  it  if  it  is 
not  already  active. 

FORTRAN  Call : 

CALL  SDRP(task,lbuf , f  ibf 1 1 , f  iefp) , ( if  lag] , [ Iparenl , f  iocbad] 
Clds)  ) 

task  »  Name  of  an  array  (REAL, INTEGER,  I  •< )  that  contains  the 
RAD50  name  of  the  target  task 

Ibuf  «  Name  of  sn  integer  array  containing  the  data  to  be 
sent 

ibfl  "  Name  of  an  integer  containing  the  nunber  of  w.^rls 
(Integers)  In  the  array  to  be  sent.  On  RSX-1 IM 
systems,  this  argument  must  always  be  13  or  must  be 
defaulted.  On  RSX-llM-PLUS  systems  this  argument  may 
be  in  th«  ra.nq*  of  1  to  255.  On  either  system  if 
this  argumenr  is  not  specified,  a  default  value  of 
13.   is  assumed. 

isfn  »  Na.Tie  of  an  Integer  containing  the  number  of  the  event 
flag  that  is  to  be  set  when  this  directive  Is 
executed  successfully. 

Iflag  ^  Name  of  an  Integer  containing  the  flag  bits 
controlling  the  execution  of  th's  directive.  They 
are  defined  as  follows: 

SD.REX  »  128.    Force  this  task  to  exit  upon 
successful  execution  of 
this  d  i  rect 1 ve 

SD.RAL  "  1      Pass  all  connections  to  the 

requested  task  (default  is  pass 
none).   If   you  specify   this 
flag,  do  not  specify  the  parent 
task  name. 

NOTE 

The  target  task  may  not  be 
a  CLI  task. 


SD.RNX  »  2      Pass  the  first  connection 

in  the  queue,  if  there  is  one, 
to  the  requested  task.   If 
you  specify  this  flag,  io  not 
specify  the  parent  task  name. 

Iparen  =>  Name  of  an  array  containing  the  RAD50  name  of  the 
parent  task  whose  connection  should  be  passed  to  the 
target  task.  The  name  of  the  parent  task  was 
returned  in  the  information  buffer  of  the  GTCMCI 
subrout  ine . 
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locbad 


ids 


Name  of  an  integer  containing  the  pool  address  of  the 
OCB  to  pass.  This  value  was  returned  in  the 
Information  buffer  of  the  GTCMCI  subroutine.  Only 
CLI  tasks  may  specify  this  parameter. 


Name  of  a:i  Integer  to  receive   the 
Directive  Status  Word. 


rontents   of   the 


Macro  Cal 1 : 

SDR PS  task.bufadr, [buflen] , [efn] , (flag] , (parent) , (ocbad) 
task    =   Name  of  task  to  be  chained  to 

butadr  *      Address  of  buffer  to  be  given  to  the  requested  task 
buflen  =   Length  of  buffer  to  be  given  to  requested  task 


•  fn 

flag 


Event  flag 

Flags   byte   controlling   the    execution    of    this 
directive.   The  flag  bits  are  deflni^d  as  follows: 

SD.REX  «>  128.  Force  this  task  to  exit  upon 
successful  completion  of  this 
d  I  rect  i ve , 

SD.RAL  *  1  Pass  all  connections  to  th« 
requested  task  (default  is  pass 
none).  If  you  specify  this  flag, 
do  not  specify  the  parent  task 
name. 


NOTE 

The  target  task  may  not  be 
a  CLI  task. 


SD.RNX  ■=  2  Pass  the  first  connection  in  the 
queue,  if  there  Is  one,  to  the 
requested  task.  If  you  specify 
this  flag,  do  not  specify  the 
parent  task  name. 

parent  =  Name  of  issuing  task's  parent  task  whose  connection 
is  to  L/G  passed.  If  net  specified,  ail  connections 
or  no  connections  are  passed  depending  on  the  flag 
byte. 

ocbad   =   Address  of  OCB  to  pass  (CLI  tasks  only) 

Macro  Expansion: 

SDR  PS  task,bufadr, [buflen] , [efn] , [ flag] , (parent] , [ocbad] 

;DIC  =  141,  DPB  LENGTH  =9  WORDS 

;TASK  NAME  IN  RADIX-50 

;S'JFFER  ADDRESS 

; EVENT  FLAG,  FLAGS  BYTE 

; BUFFER  LENGTH 

; PARENT  TASK  NAME 

fADDRESS    OF    OCB 


.BYTE 

141. ,9. 

.RAD50 

/task/ 

.WORD 

BUFADR 

.BYTE 

EFN, FLAG 

.WORD 

BUFLEN 

.RAD50 

/PARENT/ 

.WORD 

OCBAD 
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Local  Symbol  Definitions: 

S.DRTK  —   RAD50  name  of  task  to  be  chained  to 

S.DRAD  —   Send  data  buffer  address 

S.DREF  —   Event  flag 

S.DRFL  —   Flags  byte: 

SD.REX  —  (200)  Force  task  to  exit  (task  issuing 
di  rect ive) 

SD.RAL  —  (1)    Pass  all  connections  to  the 

requested  task  (default  is  pass 
none).   If   you  specify   this 
Llag,  do  not  specify  the  parent  task 
name  • 

SD.RNX  —  (2)    Pass  the  first  connection  in  the 
queue,  if  there  is  one,  to  the 
requested  task.   If  you  specify 
this  flag,  do  not  specify  the 
parent  task  name. 


S.DRBL   -- 

S.DRPT   — 
S.DROA   — 
DSW  Return  Codes: 


Length  of  send   data   packet   'Always   13  v^ords   for 
RSX-llM,  up  to  255  words  for  RSX-llM-PLUS) 

Name  of  parent  whose  OCB  should  be  passed 

Address  of  OCB  to  pass  (CLIs  only) 


IE. ITS  —  A  task  that  is  not  a  CLI  specified  a  CLI  only 
parameter,  or  attempted  to  pass  all  connections  to  a 
CLI. 

lE.NVR   —  No  offspring  control  block  from  specified  parent. 

lE.ALG  --  A  CLI  spedfied  a  parent  name  and  an  offspring 
control  block  address  that  did  not  describe  the  same 
connection,  or  either  a  parent  name  or  an  OCB  address 
was  specified  and  the  oass  all  connections  flag  was 
set. 

IE, IBS   —   Length  of  send  packet  is  illegal.   On  RSX-llM  systems 

the    send   packet   must  be   13.    bytes   long.    On 

RSX-llM-PLUS  systems  the  send  packet  may  be   up  to 
255.   bytes  long. 

lE.UPN  —  Insufficient  dynamic  memory  to  allocate  a  send 
packet,  offspring  control  block,  task  control  block, 
or  partition  control  block. 

IE, INS  —  The  specified  task  is  an  ACP  or  has  the  no-send 
attribute . 


lE.IEF 


lE.ADP   — 


An  invalid  event  flag  number  was  specified  (EFN<0  or 
EFN  >96  if  group  global  event  flags  exist.  EFN  >6'1 
if  not) . 


Part  of  the  DPB  or  exit  status  block  Ii 
issuing  task's  address  space. 


out      of      the 


IE. SOP      —      Die    or    DPB    Size    is    invalid, 
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Notes : 

1. 


If  the  directive  is  rejected,  the  state  of  the  specified 
event  flag  is  indeterminate. 

If  the  specified  event  flaq  is  group  global,  the  use  count 
for  the  event  flag's  group  is  incremented  to  prevent 
premature  elimination  of  the  event  flags.  The  use  count  jS 
run  down  when: 

•  Status  is  returned  from  the  connected  tasks 

•  The  issuing  task  exits  before  status  is  r  turned. 
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SETF$ 


5.3.64      Set    Event    Flag 

The    Set    Ev^nt    Flag    directive    instructs    the    system    to    set    an      indicated 
event    flag,    reporting    the    flag's    polarity   before    setting. 

FORTRAN  Call : 

CALL   SETEF    (efn[,Ids] ) 

efn   =   Event  flag  number 
ids   =  Directive  status 
Macro  Call  : 

SETF$     efn 

efn      =      Event    flag    number 
Macro    Expansion: 

SETF$  52. 

.BYTE  33., 2  ;SETF$    MACRO    DIC,    DPB    SIZE=2    WORDS 

.WORD  52.  ;EVENT    FLAG    NUMBER    52. 

Local    Symbol    Definitions: 

S.ETEF      --      Event    flag    number    (2) 
DSW   Return    Codes: 

IS.CLR      —      Flag    was   clear. 

IS. SET      —      Flag    was    already   set. 

lE.IEF  —  Invalid  event  flag  number  (EFN<1,  or  EFN>96  if  group 
global  event  flags  exist  for  the  task's  group;  or 
EFN>64    if    not) . 

lE.ADP  —  Part  of  the  DPB  is  out  of  the  issuing  task's  address 
space . 

lE.SDP      —      Die   or    DPB   size    is    invalid. 
Note: 

Set    Event    Flag    does    not   declare    a    significant    event;         it      merely 
sets    the    specified    flag. 
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SFPA$ 

5.3.65   Specify  Floating  Point  Processor  Exception  AST 

The  Specify  Floatinq  Point  Processor  Exception  AST  directive  instructs 
the  system  to  record  one  of  the  two  following  cases: 

•  Floating  Point  Processor  exception  ASTs  for  the  Issuing  task 
are  desired,  and  the  Executive  is  to  transfer  control  to  a 
specified  address  when  such  an  AST  occurs  for  the  task. 

•  Floating  Point  Processor  exception  ASTs  for  the  issuing  task 
are  no  longer  desired. 

When  an  AST  service  routine  entry  point  address  Is  specified,  future 
Floating  Point  Processor  exception  ASTs  will  occur  for  the  Issuing 
task,  and  control  will  be  transferred  to  the  indicated  location  at  the 
time  of  the  AST's  occurrence.  When  an  AST  service  entry  point  address 
is  not  specified,  future  Floating  Point  Processor  exception  ASTs  will 
not  occur  until  the  task  issues  a  directive  that  specifies  an  AST 
entry  point.   See  Notes  below. 

FORTRAN  Call : 

Not  supported 
Macro  Cal 1 : 

SFPA$     fast) 

ast   =   AST  service  routine  entry  point  address 

Macro  Expansion: 

='LTAST 

;SFPA$  MACRO  DIC,  DPB  SI^E=2  WORDS 
.-ADDRESS  OF  FLOATING  POINT  AST 

Local  Symbol  Definitions: 

S.FPAE   --   AST  entry  address  (2) 
DSW  Return  Codes: 

IS. sue   —   Successful  completion. 

lE.UPN   —   Insufficient  dynamic  memory. 

IE. ITS  —  AST  entry  point  address  Is  already  unspecified  or 
task  was  built  without  floating-point  support  (FP 
switch  not  specified  in  Task  Builder  .TSK  file 
spec  i  f icat  ion)  . 

lE.^^T  --  Directive  was  issued  from  an  AST  P^rvice  routine,  or 
ASTs  are  disabled. 

TE.ADP  —  Part  of  the  DPB  is  out  of  the  issuing  task's  address 
space . 

lE.SDP   —   DIC  or  DPB  size  is  invalid. 


SFPA$ 

FLTAST 

.BYTE 

111.  ,2 

.WORD 

FLTAST 
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Notes : 

1, 


A  Specify  Floating  Point 
dynamic  memory. 


Processor   Exception   AST   requires 


The  Executive  queues  Floating  Point  Processor  exception  ASTs 
when  a  Floating  Point  Processor  exception  trap  occurs  for  the 
task.  No  future  ASTs  of  this  kind  will  be  queued  for  the 
task  until  the  first  one  queued  has  actually  been  effected. 

The  Floating  Point  Processor  exception  AST  service  routine  is 
entered  with  the  task  stack  in  the  following  state: 

SP+12  -  Event  flag  mask  word 
SP+10  -  PS  of  task  prior  to  AST 
SP+06  -  PC  of  task  prior  to  AST 
SP+04  -  DSW  of  task  prior  to  AST 
SP+02  -  Floating  exception  code 
SP+00  -  Floating  exception  address 

The  task  must  remove  the  floating  exception  code  and  address 
from  the  task's  stack  before  an  AST  Service  Exit  (see  Section 
5.3.4)  directive  is  executed. 


This  directive  cannot  be  Issued  either  from 
routine  or  when  ASTs  are  disabled. 


an   AST   service 


This  directive  applies  only  to  the  Floating  Point  Processor. 
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SMSG$ 


5.3.6fi   Send  Message 

The  Send  Messaqe  directive  instructs  the  system  to  create  and  send  a 
formatted  data  packet  to  a  system-defined  target  task.  The  only  valid 
target  for  the  Send  Message  directive  Is  Error  Logger,  and  the  Error 
Logging  formatted  data  packet  Is  an  Error  Log  packet.  The  task  that 
issues  the  SMSGS  directive  must  be  privileged.  The  valid  system 
defined  target  and  identlfl-r  are: 


TARGET 
IDENTIFIER 


CODE 


Error    Logging  SM.SER 

FORTRAN  Call  : 

CALL  SMSG  (itgt,!buf , Ibufl , lprm,lprml , Ids) 

Itgt    «   The  name  of  the  Integer  containing  the  target   object 
(currently  only  SM.SER  is  defined) 

ibuf    =   The  name  of  an  Integer  array  containing  the   data   to 
be  inserted  Into  the  formatted  data  packet, 

ibufl   =   The  name  of  an  integer  containing  the  length   of   the 
ibuf  array. 

iprm    =   The   name   of   an   integer    array   containing    any 
additional  parameters. 

Iprml   =   The  name  of   ar   Integer   containing   the   number   of 
parameters  in  the  Iprm  array. 

Ids     =   The  name   of   an   optional   integer   to   receive   the 
directive  stat'is. 


MACRO  Cal  1 : 

SMSG$  tgt ,buf  ,len,<pr i , 


,prn> 


tgt  »   Target  identifier 

buf  »   Address  of  optional  data  b'jffer 

l«n  =   Length  in  bytes  of  optional  data  buffer 

pri,...,prn   =   Target-specific  parameter  list: 
Parameter  list  for  Error  Logging 

SMSGS  SM.SER,b'if,len,<typ,3ub,lun,msk> 
typ   =   Error  Log  packet  type  code 
sub   =   Error  Log  packet  subtype  code 
I'jn   =   Logical  unit  number  of  device 
msk   =   Control  mask  word 
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The  directive  creates  an  Error  Log  packet  of  the  specified  type  and 
subtyps  codes.  If  you  specify  a  LUN,  the  directive  also  records 
Information  about  the  device  to  which  the  LUN  refers.  The  control 
mask  word  sets  flags  to  zero  I/O  and  error  counts  on  the  device 
specified,  as  shown  belov: 

Control  mask  word  flag: 

SM.ZER   --   Zeroes  device  I/O   and   error   counts   for   device 
specified  oy  LUN 

The  directive  also  creates  the  following  subpackets  and  places  them  In 
the  Error  Log  packet  in  the  order  listed  below: 

1.  He.ider  Subpacket  -  The  header  subpacket,  which  contains  the 
type  and  subtype  codes,  the  timv  stamp,  and  system 
Identification,  is  always  recorded. 

2.  Task  v^ubpacket  -  The  task  subpacket,  which  identifies  the 
task  that  Issued  the  directive.  Is  always  recorded, 

3.  Device  Subpacket  -  The  device  subpacket,  which  Identifies  the 
device,  is  recorded  if  the  directive  specifies  a  LUN 
argument . 

4.  Data  Subpacket  -  The  data  subpacket  Is  recorded  it  the 
directive  specifies  an  address  and  length  of  an  optional  data 
buffer . 

Macro  Expansion  (with  Error  Logging  target) 


SMSGS 
.BYTE 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 
.WORD 


SM.ERR   DATBUF,DATLEN,<PR1,PR?,PR1,PR4> 


DIG, 8 

SM.ERR 

DATBUF 

DATLEN 

PRl 

PR2 

PRl 

PR  4 


SMSGS  MACRO  DIC,  DPB  SIZE=8  WORDS 
TARGET  rDENTIFIEF.  -  ERROR  LOGGING 
DATA  BUFFER  ADDRESS 
DATA  BUFFER  LENGTH 
PAaAMETFR   l 
PARAMEIEft   2 
PARAMETER   3 
PARAMETER   4 


Local  Symbol  Definitions: 

S.MTGT  --   Target  Identifier  (2) 

S.MDBA  --   Buffer  address  (2) 

3.MDBL  --   Buffer  length  (2) 

S.MPRL  --   Parameter  list 

S.MERR  --   Error  Log  Target  Identifier 
DSW  Return  Codes: 

IS. sue  —   Successful  completion. 

lE.ILU  --   Invalid  LUN  (Error  Log  target  only). 

lE.SDP  -   DIC  or  DPB  size  is  invalid. 
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lE.ULN  —  Unassigned  LUN  (Error  Log  target  only) . 

lE.UPN  —  Insufficient  dynamic  memory. 

IE. INS  --  Target  task  is  not  installed. 

IE. ITS  —  Invalid  target  identifier  or  invalid  control  mask. 

lE.ADP   --   Part  of  the  DPB  or  data  buffer  is  out  of  the   issuing 
task's  address  space. 
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SNXC$ 


5.3.67  Send  Next  Coamand 

The  Send  Next  command  directive  allows  a  task  that  is  servicing  a  CLI 
command  to  Inform  the  system  that  the  command  execution  is  complete. 
This  normally  happens  automatically  when  tiie  task  exits,  and  this 
directive  is  not  necessary  if  the  task  wiil  exit  when  it  completes  the 
command.   It  is  intended  for  tasks  that  do  not  exit  at  this  point. 

The  task  of  concern  here  is  the  final  task  involved  in  the  command 
processing.  For  example,  a  CLI  that  passes  the  command  to  another 
task  using  the  RPOI$  or  SDRP$  directives  and  exits  need  not  issue  an 
SNXC$  directive.  If  the  CLI  were  to  do  all  the  processing  necessary 
for  a  command,  not  pass  it  to  another  task,  and  go  on  to  the  next 
command,  it  would  have  to  ii>sue  an  SNXC$  directive. 

Issuing  this  directive  causes  a  prompt  request  to  be  generated  if  one 
would  have  occurred  on  task  exit,  and  will  cause  the  terminal  driver 
to  send  the  next  command  to  the  dispatcher  if  the  terminal  is  in 
serial  execution  mode. 

A  nonprivileged  task  nay  specify  only  its  TI:.   A  privileged  task  or  a 


CLI   task  may  bpfcclfy  any  terminal, 
default  is  the  issuing  task's  TI:. 

FORTRAN  Ceil: 

CALL  SNXC([dnam]  [,iunit]  [,ids) ) 

dnam  >  Device  name  (ASCII). 


If  no  terminal  is  specified,  the 


If  noi:  specified,  TI:   is  used. 


iunit  »  Unit  number  of  the  terminal  from  which  the  command   is 
to  be  sent. 


ids 
Macro  Call : 
SNXC$ 


Integer  to  rec:.'ive  the  directive  status  word. 


[dnam] [ ,unum] 

dnam  =  Device  name  (ASCII).   If  not  specified,  TI:   is  used. 

unum  =>  Unit  number  of  the  terminal  from  which  the  command   is 
to  oe  sent. 


Macro  Expansion: 


SNXC$  TT,3 
.BYTE      127., 3 
.ASCII     /TT/ 
.BYTE      3,0 


;SNXC$  MACRO  DIC,  DPS  SIZE-3  WORDS 
; ASCI I  DEVICE  NAME 
;UNIT  NUMBER  IS  3 
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DSW  Return  Codes j 

lE.IDU   —   The  specified  device  does   not   exist   or   is  not   a 
terminal .       ^ 

lE.PRI   —  Nonprivileged  task  specified  a   termiml  other   than 
its  own  TI:. 

lE.ADP  —   Part  of  the  DPB  is  out  of  the  issuing  task's   address 
space. 

IE. SOP  —   DIG  or  DPB  size  is  Invalid. 
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SPEA$ 


5.3.68  Specify  Parity  Error  AST 

The  Specify  Parity  Error  AST  directive  enables  a  task  to  specify  an 
AST  service  routine  to  be  entered  if  a  hardware  parity  error  occurs. 
If  an  AST  address  is  not  specified,  any  previously  specified  parity 
error  AST  is  canceled-  Upon  entering  the  AST  service  routine,  the 
stack  contains  the  following  information; 


SP+62 
SP+60 
SP+56 
SP+54 
SP+52  ~ 
SP+50  — 
SP+46  ~ 
SP+44  — 
SP+42  — 
SP+40  -- 
SP+36  — 
SP+34  — 
SP+32  — 
SP+30  -- 
SP+26  ~ 
SP+24  -- 
SP+22  ~ 
SP+20  -- 
SP+16  -- 
SP+14  -- 
SP+12  — 
SP+10  ~ 
SP+06  — 
SP+04  — 
SP+02  — 
SP+00  -- 

FORTRAN  Call: 


Event  flag  mask  word 
PS  of  task  prior  to  AST 
PC  of  task  prior  to  AST 
Task's  directive  status  word 


Contents  of  memory  parity  CSRs 
(hardware-dependent  information) 


Contents  of  cache  control  register 

Contents  of  memory  system  error  register 

Contents  of  high  error  address  register 

Contents  of  low  error  address  register 

Processor  identification  (single  processor  system-0) 

Number  of  bytes  to  add  to  SP  to  clean  the  stack  (52) 


Not  supported 
Macro  Call : 

SPEA$    (ast) 

ast      «     AST  service   routine   entry  point   address 
Macro   Expansion: 


SPEA$ 

PTYERR 

.BYTE 

165. ,2 

.WORD 

PTYERR 

;SPEA$   MACRO   DIC,    DPB    SIZE-2   WORDS 
;PARITY   ERROR   AST    ROUTINE   ADDRESS 


Local    Symbol    Definitions: 

S.PEAE      —      Parity  error   AST  routine   address    (2) 


5-167 


DIRECTIVE  DESCRIPTIONS 

DSW  Return  Codes: 

IS. sue   —  Successful  completion. 

lE.UPN   —   Insufficient  dynamic  storage. 

IE. ITS   —  ASTs  already  not  desired. 

IE. AST  —  Directive  was  issued  from  an  AST  service  routine,   or 
ASTs  are  disabled. 

lE.ADP   —   Part  of  the  DPB  is  out  of  the  issuing  task's   address 
space. 

lE.SDP   --   Die  or  DPB  size  Is  invalid. 
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SPNDSS 


5.3.69   Suspend  ($S  Porm  Recommended) 

The  Suspend  directive  Instructs  the  system  to  suspend  the  execution  of 
the  Issuing  task.  A  task  can  suspend  only  Itself,  not  another  task. 
The  task  can  be  restarted  either  by  a  Resume  directive,  or  by  jn  MCR 
or  DCL  Resume  command. 

FORTRAN  Call : 

CALL  SUSPND    (  (ids)  1 

ids   =   Directive  status 

Macro  Call : 

SPNDSS    [err] 

err   »   Error  routine  address 

Macro  Expansion: 

;PUSH  DPB  ONTO  THE  STACK 

;3PNDSS    MACRO    DIG,     DPB    SIZE-1    WORD 

;TRAP   TO    THE    EXECUTIVE 

;BRANCH    IF    DIRECTIVE    SUCCESSFUL 

.-OTHERWISE,    CALL    ROUTINE    "ERR" 

Local    Symbol    Definitions: 

None 
DSW   Return    Codes: 

IS.SPD      —      Successful    completion    (task    was    suspended). 

lE.ADP      --      Part   of    the    DPB    is      out   of    the    Issuing    tank's    address 
space . 

lE.SDP      --      Die    or    DPB    size    is    Invalid. 

Notes : 

1.  A  suspended  task  retains  control  of  the  system  resources 
allocated  to  it.  The  Executive  makes  no  attempt  to  free 
these  resources  until  a  task  exits. 

2.  A  suspended  task  is  eligible  for  checkpointing  unless  it  Is 
fixed  or  declared  to  he  noncheckpo Intable . 

3.  Because  this  directive  requires  only  a  1-word  DPB,  the  SS 
form  of  the  macro  Is  recommended.  It  requires  less  space  and 
executes  with  the  same  speed  as  that  of  the  DIRS  macro. 


SPNDSS 

ERR 

MOV 

;pc)+,-(SP) 

.BYTE 

45.,  1 

EMT 

377 

BCC 

.+6 

JSR 

PC,  ERR 
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SPRAS 

5.3.70   Specify  Power  Recovery  A3T 

The  Specify  Power  Recovery   AST   directive   Instructs   the   system   to 
record  ore  of  the  two  following  cases: 

1.  Power  recovery  ASTs  for  the  Issulnq  task  are  desired,  and 
control  Is  to  be  transferred  when  a  powerfail  recovery  AST 
occurs. 

2.  Power  recovery  ASTs  for  the  Issuing  task  are  no  lonqer 
desl red  . 

When  an  AST  service  routine  entry  point  address  is  specified,  ''utui« 
power  recovery  ASTs  will  occur  for  the  Issuing  task,  and  control  will 
be  transferred  to  the  Indicated  location  at  the  time  of  the  AST's 
occurrence.  When  an  AST  service  entry  point  address  is  not  specified 
future  power  recovery  ASTs  will  not  occur  until  an  AST  entry  point  Is 
again  sp^jcifled.   See  Notes  below. 

FORTRAN  Call : 

To  establish  an  AST: 

EXTERNAL   sub 
CALL  PWRUP  (sub) 


sub   =   Name   of   a   subroutine   to   be   executed   upon 
recovery.   The  PWRUP  subroutine  will  effect  « 

CALL  sub  (no  argumer  s)  . 


powe  r 


The  subroutine  is  called  as  a  result  of  a  power 
recovery  AST,  and  therefore  may  be  controlled  at 
critical  points  by  using  DSASTR  and  FNASTR  subroutine 
calls. 

To  remove  an  AST: 

CALL  PWRUP 
Macro  Call; 

SPRAS    fast] 

ast   =   AST  servi'je  routine  entry  point  address 

Macro  Expansion: 

S.  AS    PWRAST 

•BYTE  109., 2  ;SPRAS    MACRO    DIC,     DPB    SrZE"2    WORDS 

.WORD         PWRAST  .-ADDRESS    OF    POWER    RECOVERY   AST 

Local    Symbol    De fin  It  lens: 

S.PRAE      --      AST  entry   address    (2) 
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DSW  Return  Codes: 

IS. sue   —  Successful  completion. 

Insufficient  dynamic  memory. 
--  AST  entry  point  address  is  already  unspecified. 


lE.UPN 
IE. ITS 
IE. AST 


lE.ADP 


--  Directive  was  issued  from  an  AST  service  routine,  or, 
ASTs  are  disabled. 

--   Part  of  the  DPS  is  out  of  the  issuing  task's  address 
space . 


TE.SDP   —  Die  or  DPB  size  is  invalid. 
Notes : 

1.  Specify  Power  Recovery  AST  requires  dynamic  memory. 

2.  The  Executive  queues  power  recovery  ASTs  when  the  power-up 
interrupt  occurs  following  a  power  failure.  No  future 
powerfail  ASTs  will  be  queued  for  the  task  until  the  first 
one  queued  has  been  effected. 

3.  The  task  enters  the  powerfail  AST  service  routine  with  the 
task  stack  in  the  following  state: 

SP+06  -  Event  flag  mask  word 
SP+04  -  PS  of  task  prior  to  AST 
SP+02  -  PC  of  task  prior  to  AST 
SP+00  -  DSW  of  task  prior  to  AST 

No  trap-dependent  parameters  accompany  a  power  recovery  AST; 
therefore,  the  AST  Service  Exit  directive  (see  Section  b.3.4) 
can  be  executed  with  the  stack  in  the  same  state  as  when  the 
AST  was  entered. 

4.  This  directive  cannot  be  issued  either  from  an  AST  service 
routine  or  when  ASTs  are  disabled. 

5.  Refer  to  Chapter  1  for  a  list  of  the  restrictions  on 
operations  that  may  be  performed  in  a  FORTRAN  AST  routine. 
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SPWN$ 

5.3.71   Spawn 

The  Spawn  directive  requests  a  specified  task  for  execution, 
optionally  queuing  a  command  line^  and  establishing  the  task's  TI :  as 
a  previously  created  virtual  terminal  unit  or  a  physical  terminal. 


If  a  command  line  is  specified,  't  is  buffered  in  the  Executive  pool 
and  queued  for  the  offspring  task  for  subsequent  retrieval  by  the 
offspring  task  with  the  Get  MCP  Command  Line  directive.  Maximum 
command  line  length  is  79  characters  on  RSX-llM  systems  and  255 
characters  on  RSX-llM-PLUS  systems. 

If  an  AST  address  is  specified,  an  exit  AST  routine  is  effected  when 
the  spawned  task  exits  with  the  address  of  the  tasK'r,  exit  status 
block  on  the  stack.  The  AST  routine  must  remove  this  word  f'om  the 
stack  before  issuing  the  AST  Service  Exit  directive. 

Special  action  is  taken  if  the  task  being  spawned  is  a  Command  Li.ie 
Interpreter  (CLI),  such  as  MCR  or  DCL.  In  this  case,  a  command  line 
must  be  specified,  and  both  the  OCB  and  the  command  line  are  queued 
for  the  interpreter  task.  MCR  and  DCL  either  handle  commands  d'rectly 
or  dispatch  them  to  another  task.  In  the  case  of  direct  execution  of 
the  command,  the  OCB  may  be  used  to  immediately  effect  the  proper  exit 
conditions  and  return  exit  status  by  an  Executive  routine.  If  KCR  or 
DCL  dispatch  another  task,  they  simply  move  the  OCB  from  their  own  OCB 
queue  directly  to  the  OCB  queue  of  the  dispatched  task.  They  also 
queue  the  command  line  for  the  dispatched  task  as  usual.  At  this 
point,  the  situation  is  exactly  the  same  as  if  the  SPWN$  directive  had 
specified  the  dispatched  task  directly.  No  exit  conditions  occur 
until  the  dispatched  task  exits. 

FORTRAN  Call : 

CALL  SPAWN  (rtname, [ iugc] , [ iumc] , [ iefn] , [ last] , [ iesb] , [ Iparm] , 
[ icml in] , [ icmlen] , [ iuni t] , [dnam] [ , ids] ) 

rtname   =   Name  (RAD50)  of  the  offspring  task  to  be  spawned. 

iugc    =   Group  code  number  for  the  UIC  of  the  offspring  task. 

iumc    =   Member  code  number  for   the   UIC   of   the   offspring 
task . 

iefn    =   Event  flag  to  be  set  when  the  offspring   task   exits 
or  emits  status. 


1.  Command  line  processing  is  not  available  for  RSX-llS  tasks, 
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last    "   Name  of   an   AST   routine   to   be   called   when   the 
offspring  task  exits  or  emits  status. 

lesb    =   Name  of  an  8-word  status  block  to   be   written   when 
the  offspring  task  exits  or  emits  status. 

Word    0  --  Offspring  task  exit  status 

Word    1  --  TKTN  abort  code 

Word  2-7  --  Reserved 


NOTE 

The  exit  status  block  defaults  to  one  word. 
To  use  the  8-word  exit  status  block,  you 
must  specify  the  logical  or  of  the  symbol 
SP.WX8  and  the  event  flag  number  in  the  lefn 
parameter  above. 


iparm  =  Name  of  a  word  to  receive  the  status  block  address 
when  the  AST  occurs. 

ictnlin  =  Name  of  a  command  line  to  be  queued  for  the 
offspring  task. 

icmlen  =  Length  of  the  command  line  (79.  characters 
max  imum)  . 

iunit  =  Unit  number  of  terminal  to  be  used  as  the  TI:  for 
the  offspring  task.  If  the  optional  dnam  parameter 
Is  not  s{>ecified,  this  parameter  must  be  the  unit 
number  of  a  virtual  terminal  created  by  the  issuing 
task;  if  a  value  of  0  is  specified,  the  TI:  of  the 
issuing  task  is  propagated.  A  task  must  be 
privileged  or  must  be  a  CLI  task  in  order  to  specify 
a  TI :   other  than  the  parent  task's  TI:. 

dnam  =  Device  name  mnemonic.  If  not  specified,  the  virtual 
terminal  is  used  as  TI:. 

=   Integer  to  receive  the  directive  status  word. 


tname, , ,  [ugc]  ,  [utr.c]  ,  [efn]  ,  [east]  ,  [esb]  ,  [cmdl  in]  ,  [cmdlen]  , 
[ unum] , [dnam] 

=   Name  {RAD50)  of  the  offspring  task  to  be  spawned. 

Group  code  number  for  the  UIC  of  the  oiCspring  task. 

=   Member  code  number  for   the   UIC   of   the   offspring 
task. 

efn     =   The  event  flag  to  be  cleared   on   issuance   and   set 
when  the  offspring  task  exits  or  emits  status. 

east    =   Address  of  an  AST  routine   to   be   called   when   the 
offspring  task  exits  or  emits  status. 
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Address  of  an  8-word  status  block  to  be  written  when 
the  offspring  task  exits  or  emits  status. 

Word    0   —  Offspring  task  exit  status 

Word    1   —  TKTN  abort  code 

Word  2-7   —  Reserved 


NOTE 

The  exit  status  block  defaults  to  one 
word.  To  use  the  8-word  exit  status 
block,  you  must  specify  the  logical  or 
of  the  symbol  SP.WX8  and  the  event  flag 
number  in  the  efn  parameter  above. 


cmdl in 

cmdlen 
unum 


dnam 


Address  of  a  command 
offspring  task. 


line   to   be  queued   for   the 


Length  of  the  command  line  (maximum  length  is  79.). 

Unit  number  of  terminal  to  be  used  as  the  TI:  for 
the  offspring  task.  If  the  optional  dnam  parameter 
Is  not  specified,  this  parameter  must  be  the  unit 
number  of  a  virtual  terminal  created  by  the  issuing 
task;  if  a  value  of  0  ir  specified,  the  TI:  of  the 
issuing  task  is  propagated.  N  task  must  be 
privileged  or  must  be  a  CLI  task  in  order  to  specify 
a  TI:   other  than  the  parent  task's  TI:. 

Device  name  mnemonic.   If  not  specified,  the  virtual" 
terminal  is  used  as  TI:. 


Macro  Expansion: 


SPWN$ 

ALPHA, , 

.BYTE 

11. , 13. 

.RAD50 

ALPHA 

.BLKW 

3 

.BYTE 

7,3 

.BYTE 

1 

.BYTE 

16. 

.WORD 

ASTRUT 

.WORD 

STBLK 

.WORD 

CMDLIN 

.WORD 

72. 

.WORD 

2 

3,7, 1, ASTRUT, STBLK, CMDLIN, 72. , 2 

;SPWNS  MACRO  DIC,  DPB  SrZE=13  WORDS 

;NAME  OF  TASK  TO  BE  SPAWNED 

:RESERVED 

:UHC    =  7    UGC  =  3 

•EVENT  FLAG  NUMBER  =  1 

[EXIT  STATUS  BLOCK  CONSTANT 

lAST  ROUTINE  ADDRESS 

(EXIT  STATUS  BLOCK  ADDRESS 

(ADDRESS  OF  COMMAND  LINE 

[COMMAND  LINE  LENGTH  "    72.  CHARACTERS 

/VIRTUAL  TERMINAL  UNIT  NUMBER  =2 


NOTE 

If   a  virtual    terminal    is   not      specified, 

one  additional  parameter  (device  name) 
can  be  added  for  a  hariware  terminal 
name.  For  example,  TT2  (instead  of  VT2) 
would  have  the  same  macro  expansion 
shown    above,    plus    the    following: 


.ASCII      /TT/ 


.-ASCII       DEVICE    NAME 


The    DPB    size    will    then   be    14   words. 


5-174 


DIRECTIVE    DESCRir"IONS 


Local    Symbol  Definitions; 

S.PWTN  --  Task   name    (4) 

S.PWXX  —  Reserved    (6) 

S.PWUM  —  User   member    code    (1) 

S.PWUG  —  User   group  code    (1) 

S.PWEF  --  Event    flag    number    (2) 

S.PWEA  --  Exit    AST   routine   address    (2) 

S.PWES  --  Exit    status    block    address    (2) 

S.PWCA  —  Command    line    address    (2) 

S.PWCL  —  Command    line    length    (2) 

S.PWVT  —  Terminal    unit    number    (2) 

S.PWDN  --  Device    name    (2) 
DSW    Return    Codes: 

IS. sue  —  Successful    completion. 

lE.UPN  —  Insufficient  dynamic  memory  to  allocate  an  offspring 
control  block,  command  line  buffer,  task  control 
block,    or    partition    control    block. 

IE. INS  ~  The  specified  task  was  not  installed,  or  It  was  a 
command  line  interpreter  but  no  command  line  was 
speci  f led . 

IE. ACT  —  The  specified  task  was  already  active  and  it  was  not 
a   command    line    interpreter. 

IE. PR!  --  Nonprivileged  task  attempted  to  specify  an  offspring 
task's   TI:      to    be   different    from    its   own. 
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DSW  Return  Codes: 

IE. IDU  --  The  specified  virtual  terminal  unit  does  not  exist, 
or   it   was  not  craatad  by  the  issuing  task,  or  the 

specified  TI:   device  is  not  a  terminal. 

lE.IEF  —  Invalid  event  flaq  number  (EFN<0,  or  EFN>96  if  group 
global  event  flaqs  exist  for  the  task's  group;  or 
EFN>64  if  not)  . 

lE.ADP  --  Part  of  the  DPB,  exit  status  block,  or  command  line 
Is  out  of  the  issuing  task's  address  space, 

lE.SDP   --   Die  cr  DPB  size  is  invalid. 

Notes: 

1.  If  the  UIC  Is  defjulted  and  the  offspring  task  Is  not  a 
Command  Line  Interpreter  (CLI),  that  task  Is  requested  to  run 
under  the  UIC  of  the  parent  task.  If  the  UIC  is  defaulted, 
the  offspring  task  Is  a  CLI,  and  the  CLI  passes  v.he  specified 
command  line  to  a  dispatched  task,  the  dlspat-heJ  task  will 
run  under  the  UIC  of  its  TI:  terminal.  See  the  notes  for 
the  Request  Task  (RQSTS)  directive  for  more  Information  about 
task  UICs. 

2.  If  the  specified  event  flag  is  group  global,  then  the  use 
count  for  the  event  flag's  group  Is  Incremented  to  prevent 
premature  elimination  of  event  flags.  The  use  count  is  run 
down  when : 

•   Status  is  returned  from  the  spawned  task. 

a   The  Issuing  task  exits  before  status  is  returned. 

^.  The  virtual  mapping  of  the  exit  status  block  should  not  be 
changed  while  the  connection  is  in  effect.  Doing  so  may 
cause  obscure  errors. 

4.  The  types  of  operations  that  a  FORTRAN  AST  routine  may 
perform  are  extremely  limited.  Please  refer  to  Chapter  1  for 
a  list  of  restrictions. 

The  following  program  Illustrates  the  use  of  the  FORTRAN  callable 
SPAWN  routine  and  the  mechanism  for  handling  ASTs  from  a  FORTRAN 
program : 


PROGRAM  SPWAST 

C 

C    This    program    Illustrates    the    jse   of    the    FORTRAN    -allablo 
C    SPAWN    routine    and    the    ase    of    a    FORTRAN   sijbproqrain    at    AST   st/»t«>, 
C   This    example    keeps    " ITMAX*    tasks    active    at    any   point    In    time 
C   without    havlri'3    several    ::oples   of    each    utility    Installed    iin.ler 
C   different    names.    The    Input    file    consists   of    slnqle    line    -ommands 
C  of    up    to    45    characters    in    length    which    Invoke    tasks    in    the    system 
C   library   UIC.    The    first    three    characters   of    the    Input    command    line 
C   are    the    name    of    the    task    to    be    lnvoked(ie:    MAC).       The    output    file 
C  consists   of    a    log    file   containing    the    command    lines   and    the    exit    status 
C  of    the    program    Invoked. 
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C 

c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 
c 

c 
c 
c 
c 
c 
c 
c 


Th«   above    Is   accoapllahad    «s    (ollowsi 


A  cumnanJ  Is  r«ad 
form  'NAM  COMMAND*,  wh« 
conmaiid  to  b*  passed  to 
Into    an    MCR    "RUN*    comma 

"RUN  SMAC/TASK-TS 
wh«c«  I  1.1  a  numbar  asa 
Is  both  known  and  unlqu 
eranaformad  conaiand  lln 
a  copy  ot  ,.,MCH  andar 
this  copy  of  . . .MCR  axt 
Issuas  a  "CONNECT*  to  t 
window  sjch  that  the  ta 
this  case,  an  arror  ne* 
axlt    status   could   not   b 


from    the    Input    file    "CMDriL.CMD*    which    has    the 
re    NAM    Is    th«    name   of    the    task    aiid    COMMAND    lit    the 

this    tauk.    This    Input    comnand    line    la    rransforneJ 
nd    line    such   as 
K»/EST»NO/CMD-*COMAND* . 

Icjned    by   this   task   so    that    the    tarijet    task   name 
e.    The   MCR  dispatcher    (MCR...I     Is    spawned    with    this 
e,    which    In    turn   causes   the   MCR...    task    to   dispatch 
the    name    MCRTnn    to    execute    this    coaaand  .      When 
ts,    in    exit    AST    Is    servl-'ed    by    this    task    which 
he    target    task    *TSKI*.    This   nethod    Introduces    a    tlnlnq 
rvjet    task   could    exit    before    the   CONNECT   Is   nade.    In 
»*q»    la   written    to    the    loq    file    Indicating    that 
e    returned   due    to    •  connect    failure. 


This    non-pr  1  vl  leqed    FORTRAN    IV-PtUS   proqran    Is    coispllod    and 
built    as.    follows: 

MCR>F4P    SPWAST,SPWAST/-SP»SI>WAST 

MCR>TKB    SPWAST/FP.SPWAST-SPWAST.LB;  (I,  l|r4P0TS/LB 


Define    data    structures 

Th*    followlnq    variables   are    kept    on    a    per    active    'Invoked    task*    basla 
For    '.ack   of   a   better    name,    each   respective   entry    Is   called    task 
Inforamat Ion   block. 


IESTAT(8,XXX) 


lEXSAO(XXX) 


I  STAT (XXX) 


ICMDLNf4S,XXX) 


PARAMETER     UMAX- 3 


COMMON    /K0M1/IESTAT(8,ITMAX)  ,  I  EX.SAD(  ITMAX)  ,  ISTAT(ITMAX)  ,  I  PAHM  ,  RTNAME  (2  ) 

COMMON    /K0M2/THISTK;16; 

COMMON    /C0MMAN/tCMDLN(4S, ITMAX) 


INTEGER     IE3TAT 
INTEGER     lEXSAO 

INTEGER     laTAT 


INTEGER    I  PAHM 
INTEGER    RTNAME 

INTEGER    THISTK 
BYTE     ICMDLN 


iexlt    status   array   for    each   task 

larray   containing    the   address   of   each    taak's    iestat 

!urray   containing    the   status    (active   vs    fret)    of 

each    task    Information   block. 
Icontains    .^Jress   of    IESTAT   at    AST   state 
icontalns    the    RA050    name    of    the    target    task    to    be 
! connected    to   at    AST  state 


I  saved    Input    command    line    per    tflsk 

Local    Input    buffer    variables 

DIMENSION     INPCOM(I) 

DIMENSION     Ml-BUFf*?) 

EQUIVALENCE     ( ISP8UF ( 1  I  , INPCOM ( I )  ) 


BYTE    INPBUF 
BYTE    INPCOM 


I  INPUT    BUFFER 

I  COMPONENT    NAME    FIELD    OF     INPBUF 


• 
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Local    variables    for    SPAWN  call 


C 
C 
C 


EXTERNAL  EXTAST 

DIMENSION  CMDLIN(79) 

BYTE  CMDLIN 
INTEGER*4  DSPNAM 

DATA     DSPNAM/6RMCR. 

Local  control  variables 


Idefine  the  name  of  tne  AST  routine  externally 

Imaximum  command  line  passed  to  Is  79.  bytes 

1  actual  command  lino  passed  to  MCR. . . 
Ivar'..ible  containing  RAD50  task  name  of  MCR... 

./Iflll  in  name  of  ...MCR  at  compile  time 


INTEGER  ITCNT    Icount  of  number  of  free  task  information  blocks 

LOGICAL  EOF      I  flag  Indicating  EOF  detected  on  command  input  file 

Misc.  local  variables 

INTEGER  IDSW     'integer  to  contain  directive  status 


C  Open  files 
C 

OPEN  (UNIT^=l,TypE='CLD' .READONLY, NAME='CMDFIL.CMD') 

OPEN  (UNIT«2,TYPE='NEW' .CARRIAGECONTROL- ' FORTRAN' , NAME« 'CMDFIL. LOG • ) 
C 

C  Initialize  Variables 
C 

ITCNT-ITMAX+1    iset  current  count  of  available  task  info  blocks 

EOF=.rALSE.      [reset  EOF  flag 

CALL  IRAD50(3,*TSK',RTNAME(i) )  Isetup  first  half  of  target  task  name 

CALL  GETTSK(THISTK(1))  Idetermine  this  task's  name  so  that 

C  STOPing  and  UfSTOPlng  may  be  done 

C 

C  Initialize  the  lEXSAD  array  such  that  each  entry  contains  the  address 
C  of  the  exit  status  block  which  has  the  corresponding  index.  This  is 
C  necessary  so  that  the  correct  exit  status  block  may  be  determined  at  AST 
C  state. 
C 

DO  5  I=1,ITMAX 

CALL    GETADR  (lEXSADC  )  ,  tESTATd,  I)  ) 
5  CONTINUE 

C 

C  Read  a  command  line  from  the  input  file  and  initialize  a  free  task  info 

C  block. 

C 

10       READ  (1,900,END=30)  I,  INPBUF      1  read  Input  co-imand  line 
ITCN'T=ITCNT-1  jone  less  free  block 

DO  20  K=1,ITMAX  Isearch  for  the  free  block 

IF  (ISTAT(K)  .NE.  0)  GOTO  20     >IF  NE,  block  is  in  use 
ISTAT(K)=1  lELSE  found  one,  mark  it  in  use 

DO  15  J=1,I  isave  command  line  for  output  later 

rCMDLN(J,K)=rNPBUF(J) 

15  CONTINUE 

DO    16   J  =  I+1,45  I  pad    saved    comdiand    line    with    spaces 

ICMDLN(J,K)="40 

16  CONTINUE 

GOTO  40  'exit  search  loop 
20       CONTINUE 

30       EOF=.TRUE.  iset  EOF  flag 

GOTO  55  'continue  to  log  exit  status  of  what-'s  currently 

C  lactive 
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C 

C  Construct  the  actual  command  line  specified  in  the  SPAWN  call 

C 

C   Write  saved  command  line  to  TI :  30  that  any  MCR  "RUN"  error  messages 

C   have  context. 

40       WRITE(5,710)  (ICMDt.N(J,K)  .J-I.IS) 
710      F0RMAT(1X,45A1) 

ENCODE  (I+3  5,800,CMDMN)  tNPCOM.K,  ( tNPBUF  ( J  )  ,  J-1 ,  I ) 
800      FORMAT ('RUN  S ' , 3A 1 , ' /TASK-TSK ' , I  1 ,  ' /EST-NO/CMD-" '  , 45A 1 ) 

CMDLrN(I+32)-"42        ladd  terminating  quote 

CMDLrN(I+33)-"15        land  terminator. 
C 

C  Spawn  MCR...  with  the  command  line  such  as: 
C 

C        "RUN  SMAC/TASK»TSK1/EST-N0/CMD-"MAC  TESTl-VESTl " " 
C 

C  At  this  point  the  second  half  of  the  RAD50  target  task  name  is  calculated 
C  so  that  the  first  exit  AST  may  issue  a  connect  after  ...MCR  exits. 

RTNAME(2)»40*40*(30+K)   [calculate  second  half  of  RAD50  tasKname 

C  Spawn  the  MCR  dispatcher  with  tht  constructed  command  line.  The  dinpa'cher 

C  will  then  spawn  a  copy  of  ...MCR  which  will  in  turn  process  the  "RUN"  command. 

45       CALL  SPAWN  (DSPNAM, , ,  1, EXTAST,  IESTAT(1 , K)  , I PARM ,CMDLIN, 1  +  33,0, , IDSW) 

C  An  error  could  be  received  from  the  SPAWN  call.  This  could  be  due  to  a 

C  variety  of  r  asons,  such  as  the  task  file  specified  was  not  found  or  there 

C  was  insuff'  lent  system  resourcas  at  the  time  the  axecutive  directive 

C  was  issued.  Only  the  lE.RSU  errors  will  be  recovered  by  waiting  for 

C  a  significant  e>'ent  and  reissuing  the  call  to  SPAWN. 

IF(IDSW+1)  50,52,54  IchecK  directive  status  returned 

C 

C  Spawn  error 

C 

50      lESTATd , K) «5  !if  mi,  uncorrectable  error  mark  status 

IESTAT(2,K)  =  IDSW  1  save  directive  status  returned  for  log 

ISTAT(K)«3  ! indicate  status  present 

GOTO  6U  Igo  write  error  to  log  file  and  cleanup 

C 

C  Spawn  error  due  to  insufficient  resources 

c 

52      CALL  WFSNE  ! wa i t  for  significant  event 

GOTO  45  1  reissue  SPAWN 

C 

C  Spawn  successful,  wait  till  ...MCR  exits  and  first  AST  has  bP9n  serviced. 

C 

54       CALL  WAITFR(l)  ! wa i t  for  ...MCR  to  exit 

C 

C  Do  not  STOP  If  connect  failed,  just  process  task  info  block  and  continue.. 

C 

IF(IESTAT(1,K)  .EQ.  6)  GOTO  60   ! ex i t  status  code  of  6  indicates 

C  connect  failure.. 

C 

C  At  this  point  a  check  is  made  to  determine  whether  this  task  has 

C  completed  its  quest.  If  there  is  no  more  input  and  all  task  information 

C  blocks  are  free,  then  exit  processing  will  be  performed. 

C 


5-179 


DIRECTIVE  DESCRIPTIONS 


IF(EOF  .AND.  (ITCNT  .  EQ.  ITMAX-t-l))  GOTO  500 

Next,  If  all  the  task  Information  blocKS  are  being  used,  or  If  there 
is  no  more  input  to  process,  this  task  Is  stopped  so  as  to  lower  its 
priority  effectively  to  zero.  This  task  will  once  again  wake  ap  when 
the  connect  AST  unstops  this  task. 

IP(ITCNT  .EQ.  I  .OR.  (EOF))  CALL  STOP 

Scan  all  the  task  information  blocks  to  process  task  information  blocks 
which  are  now  waiting  for  cleanup  and  log  file  processing. 


60 
C 


61 

62 
C 

63 

64 

65 

66 

67 
68 

70 


DO  70  K-1, ITMAX 
IF  (ISTAT(K)  .NE. 


WRITE  (2, 
GOTO  (62, 
WRITE  (2, 
GOTO  68 
WRITE  (2, 


[search  task  information  blocks  for 
the  task(a)  which  exited 
3)  GOTO  70     I  if  oq,  then  offspring  task  connect  AST 
has  not  occurred  for  this  task 

901)  (ICMDLN(J,K) ,J-1, 45)        Iwrite  cmdl in  to  log  file 
63,64,61,65,66,67) , (IESTAT(1,K)  .AND.  "377)+l  idecode  exit  status 

902)  (1ESTAT(1,K)  .AND.  -377)  (unknown  exit  status 


GOTO  68 
WRITE  (2, 
GOTO  68 
WRITE  (2, 
GOTO  68 
WRITE  (2, 
GOTO  69 
WRITE  (2, 
GOTO  68 
WRITE  (2, 
ISTAT{K)- 
lESTATd, 
ITCNT-ITC 
CONTINUE 
GOTO  10 


903) 

904) 
905) 
906) 
907) IESTAT(2,K) 

908)IESTAT(2,K) 

0 

K)»0 
NT  +  1 


I EXSWAR  --  warning 
lor  none  returned 

lEXSSUC  --  success 

lEXSERR  --  error 

lEXSSEV  --  severe  error 

I  internal  --  SPAWN  failure 

I  internal  --  CONNECT  failure 
I  free  up  task  info  block 
linitiallze  exit  status 
[adjust  free  task  Info  block  ct 


900 
901 
902 
903 
904 
905 
906 
907 
909 


FORMAT(0. 45A1) 

FORMATCS'  ,45A1) 

FORMATC*' , 'Unknown    exit    status    »',r3) 

FORMATC*' ,  '  <<   Warning') 

FORMAT('+' , ' <<    Success') 

FORMATC*'  , '  <<    Error'  ) 

FQRMAT('  +  ' ,  '  <<r    Severe   error') 

FORMATC*' , '  <<    Spawn    error,    DSW    -',13) 

FORMATf '+' , ' <<   Connect    error,    DSW    -',13) 


C 

C  Exit  cleanly  by  closing  all  files 

C 

500 


CLOSE  (UNIT' 
CLOSE  (UNIT= 
CALL    EXIT 


ielose 
lelase 
I  ex  it 


input 
output 


file 
file 


LUN 
LUN 


END 
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SUBROUT     INE 


E    X    T    A    S    T 


INTEGER 

lESTAT 

INTEGER 

lEXSAD 

INTEGER 

ISTAT 

c 

INTEGER 

I  FARM 

INTEGER 

RTNAME 

c 

PARAMETER  ITMAX-3 

COMMON  /KOM  l/I ESTAT (8 , ITMAX) , I EXSAD ( ITMAX)  , ISTAT ( ITMAX) , IPARM, RTNAME ( 2  1 

COMMON  /KOM2/THISTK(16) 

lexlt  status  array  for  each  task 

larray  containing  the  address  of  each  task'i  lESTAT 
larray  containing  the  status  (active  vs  free)  of 
each  task  information  block, 
icontains  address  of  lESTAT  at  AST  state 
(contains  the  RAD50  name  ot  the  target  task  to  be 
iconnected  to  at  AST  state 
INTEGER  THISTK 

EXTERNAL  TSKEXT 
C 

C  Using  IPARM,  which  contains  the  address  of  the  exit  status  block  array, 
C  find  the  task  Information  block,  by  comparing  this  with  the  address  of  each 
C  exit  status  block  array . (contained  in  lEXSAD) 
C 

DO  10  I -1,  ITMAX 

IF  (lEXSAD(I)  .E(J.  IPARM)  GOTO  20  I  found  the  task  Info  block 
10       CONTINUE 

GOTO  30 

20      ISTAT(I)-2  lindlcate  . . .MCR  has  ex i t«d 

C 

C  Try  to  connect  to  the  target  task 

C 

CALL    CNCT(RTNAME(U ,2, TSKEXT, IESTAT(1, I) , IPARM, IDSW) 

IF(IDSW    .EQ.     1)    GOTO    30  lIF    EQ,    then    successful    connect 

lESTATd,  I;»6  lelse    pass   connect    failed    status 

I ESTAT (2, I) -IDSW 

ISTAT{I)-3  imark  task  info  block  as  done. 

RETURN     Ireturn  from  AST  state  (returns  to  internal  AST  handler) 

END 


3b 


SUBROUTINE 


TSKEXT 


20 
30 


PARAMETER  ITMAX-3 

COMMON  /KOM l/I ESTAT (8, ITMAX), I EXSAD (ITMAX)  , ISTAT ( ITMAX)  ,  I  FARM , RTNAME (2 ) 
COMMON  /KOM2/THISTK(16) 

lexlt  status  array  for  each  task 

larray  containing  the  address  of  each  task's  IE3TAT 

larray  containing  the  status  (active  vs  free)  of 
each  task  Information  block. 

Icontains  address  of  lESTAT  at  AST  state 

icontains  the  RAD50  name  of  the  target  task  to  be 

iconnected  to  at  AST  state 

iThis  task's  name  (so  that  an  UNSTOP  may  be  performed) 


INTEGER 
INTEGER 
INTEGER 


lESTAT 

IEX3AD 
ISTAT 


INTEGER  IPARM 
INTEGER  RTNAME 


INTEGER  THISTK 
Find  exit  status  block 


DO  10  I-l,  ITMAX 

IF  (lEXSADd)  .EQ. 

CONTINUE 

GOTO  30 

ISTAT(I)-3 

CALL  USTP(THISTK) 


RETURN 


END 


IPARM)  GOTO  20  1  found  the  task  Info  block 


I  indicate  AST  has  been  serviced 
IL/NSTOF   this  task 


Ireturn  from  AST  state  (returns  to  internal  AST  handler) 
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5.3.72   Specify  Receive  Data  AST 

The  Specify  Receive  Data  AST  directive  instructs  the  system  to  record 
one  of  the  following  two  cases; 

•  Receive  data  ASTs  for  the  Issuing  task  are  desired,  and  the 
Executive  transfers  control  to  a  specified  address  when  data 
has  been  placed  in  the  task's  receive  queue 

•  Receive  data  ASTs  for  the  issuing  task  are  no  longer  desired. 

When  the  directive  specifies  an  AST  service  routine  entry  point, 
receivo  data  ASTs  for  the  task  will  subsequently  occur  whenever  data 
has  been  placed  in  the  tas:<'s  receive  queue;  the  Executive  will 
transfer  control  to  the  specified  address. 

When  the  directive  omits  an  entry  point  address,  the  Executive 
disables  receive  data  ASTs  for  the  issuing  task.  Receive  data  ASTs 
will  not  occur  until  the  task  Issues  another  Specify  Receive  Data  AST 
directive  that  specifies  an  entry  point  addressj.   See  Notes  below. 

FORTRAN  Call : 

Neither  the  FORTRAN  language  nor  the  ISA  standard  permits  direct 
linking  to  system  trapping  mechanisms;  therefore,  this  dlrt-.-tlve 
Is  not  available  to  FORTRAN  tasks. 

Macro  Cal 1  : 

SRDA$    [ast] 

ast   =   AST  service  routine  entry  point  address 

Macro    Expansion: 

SRDAS         RECAST 

.BYTE  107., 2  ;SRDA$    MACRO    DIC,     DPB    SIZE-2    WORDS 

.WORD         RECAST  ;ADDRESS    OF    RECEIVE    AST 

Local    Symbol    Definitions: 

S.RDAE      --      AST  entry   address    (2) 
DSW   Return    Codes: 

IS. sue      --      Successful    completion. 

lE.UPN      —      Insufficient   dynamic   memory. 

IE. ITS      --      AST  entry   point    address    Is   already   unspecified. 

IE. AST      --      Directive    was    Issued    from    an    AST   service    routine,      or 
ASTs    are   d  isabled  . 

lE.ADP      —      Part    of    the    DPB    is    out    of    the    Issuing    task's      address 
space . 

lE.SDP      --      DIC   or    DPB    size    Is    Invalid. 
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Notes: 
1. 
2. 


A  Specify  Receive  Data  AST  requires  dynamic  memory. 

The  Executive  queues  recflve  data  ASTs  when  a  message  Is  sent 
to  the  task.  No  future  receive  data  ASTs  will  be  queued  for 
the  task  until  the  first  one  queuod  has  been  effected. 

The  task  enters  the  recleve  data  AST  service  routine  with  the 
task  stack  In  the  following  state: 

SP+06  -  Event  flag  mask  word 
SP+04  -  PS  of  task  prior  to  AST 
SP+02  -  PC  of  task  prior  to  AST 
SP+00  -  DSW  of  task  prior  to  AST 

No  trap-dependent  parameters  accompany  a  ro.;elve  data  AST; 
therefore,  the  AST  Service  Exit  directive  (see  Section  S.3.4) 
must  be  executed  with  the  stack  in  the  same  state  as  wher  the 
AST  was  effected  . 


This  directive  cannot  be  issued  either  from 
routine  or  when  ASTs  are  disabled. 


an 


AST 


serv  ice 
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5.3.73   Specify  Requested  Exit  AST  Directive  -  SREAS  or  SREX$ 

The  Specify  Requested  Exit  AST  directive  allows  the  task  Issuing  the 
directive  to  specify  the  AST  service  routine  to  be  entered  if  an 
attempt  Is  made  to  abort  the  task  by  a  directive  or  MCR  or  DCL  AflO 
command.  This  allows  a  task  to  enter  a  routine  for  clean-up  Instead 
of  abruptly  aborting. 

If  an  AST  address  is  not  specified,  any  previously  specified  exit  AST 
Is  canceled. 

Privileged  tasks  enter  the  specified  AST  routine  each  time  an  abort  is 
issued.  However,  subsequent  exit  ASTs  will  not  be  queued  until  the 
first  exit  AST  has  occurred. 

Nonpr ivlleqed  tasks  enter  the  specified  AST  routine  only  once. 
Subsequent  attempts  to  abort  the  task  will  actually  abort  the  task. 

SREXS  is  the  preferred  form  of  this  directive.  The  differences  are 
explained  In  Notes  1  and  2  below. 

FORTRAN  Call : 

CALL  SREA(ast[  ,lds!  ) 

ft#t     "   Name  of  the  externally  declared  AST  subroutine 

Ida     "   Name  of  an   optional  integer  to  receive  the   Directive 
Status  Word 

CALL  SREX(ast , ipblk, ipblkl , r dummy 1 [ ,lds) ) 

ast    «   Name  of  the  externally  declared  AST  subroutine 

Ipblk   =   Name    of   an    integer    array   to    receive    the 
trap-dependent  parameters 

Ipblkl  =   Number  of  parameters  to  be  returned   into   the   Ipblk 
array. 

dummy   'i   Reserved  for  future  use 

Ids     =   Name  of  an  optional  integer  to  receive  the   Directive 
Status  Word 

Macro  Cal 1 : 

SREAS    (ast) 

SREXS    [ast] ( , dummy] 

ast    -  AST  service  routine  entry  point  address 
dummy  =  Reserved  for  future  expansion 
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Macro  Expansion: 

SREA$  REQAST 
.BYTE  167., 2 
.WORD    RECAST 


SREX$ 

REQAST 

.BVTE 

167. ,3 

.WORD 

REQAST 

.WORD 

0 

;r.PEA$  MACRO  DIG,  DPB  SIZE=2  WORDS 
;EXIT  AST  ROUTINE  ADDRESS 


SREX$  MACRO  DIC,  DPB  SIZE=3  WORDS 
EXIT  AST  ROUTINE  ADDRESS 
RESERVED  FOP  FUTURE  EXPANSION 


NOTE 

The  DPB  length  for  the  SREA$  form  of  the 
directive  is  two  words.  For  the  SREX$ 
irorm  of  the  directive,  it  is  three 
words. 


Local    Symbol    Definitions: 

S.REAE      —      Exit    AST    routine    address    (2) 
DSW    Return    Codes: 

IS. sue      —      Successful    completion. 

lE.UPN      —      Insufficient   dynamic    storage. 

IE. AST  —  Directive  was  issued  from  an  AST  service  routine,  or 
ASTs    are   disabled. 

IE. ITS  —  ASTs  already  not  desired,  or  nonpr Ivileged  task 
attempted  to  respeclfy  or  cancel  the  AST  after  one 
had    already  occurred. 

lE.ADP  —  Part  of  tho  DPB  is  out  of  the  issuing  task's  address 
space. 

lE.SDP      —      DIC   or    DPB   size    is    invalid. 
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The  SREX$  form  of  the  directive  is  recommended  for  tasks  that 
wish  to  handle  all  privileged  and  nonpr iv i 1 eqed  abort 
attempts  that  do  not  violate  multiuser  protection  checks. 
The  issuing  task  can  use  the  information  returned  on  the 
stack  for  this  version  of  the  directive  to  decide  how  to 
handle  the  abort  attempt. 

After  specifying  a  requested  exit  AST  using  Ihe  SREXS  form  of 
the  directive,  the  issuing  task  will  encer  the  AST  service 
routine  if  any  attempt  is  made  to  abort  the  task.  On  systems 
with  multiuser  protection,  nonpr iv il eged  abort  attempts  must 
originate  from  the  same  TI:   as  that  of  the  issuing  task„ 

When  the  AST  service  routine  is  entered  and  the  AST  has  been 
specified  using  the  SREXS  version  of  ("he  directive,  the 
task's  stack  is  in  the  following  state: 

SP+12  -  Event  flag  mask  word 
SP+10  -  PS  of  task  prior  to  AST 
SP+06  -  PC  of  task  prior  to  AST 
SP+04  -  DSW  of  task  prior  to  AST 
SP+02  -  Trap-dependent  parameter 
SP+00  -  Number  of  bytes  to  add  to 


SP  to  clean  stack  {^) 


The  trap-dependent  parameter  is  formatted  as  follows: 

Bit  C  =  0  if  the  abort  attempt  WuS  privileged 

=  1  if  the  abort  attempt  was  nonpr ivileged 

Bit  1  =  0  if  the  ABRTS  directive  was  issued 

=  1  if  the  MCR  or  DCL  cl)ort  command  was  used 


Bits  2-15  are  reserved  for  future  use 

The  task  must  remove  the  trap-dependent  parameters  from  the 
stack  before  an  AST  Service  Exit  directive  is  executed.  The 
recommended  method  is  to  add  the  value  stored  in  SP+00  to  SP. 
This  is  also  the  only  recommended  way  to  access  the 
non-trap-dependent  parameters  on  the  stack. 

The  SREAS  form  of  the  directive  is  recommended  for  privileged 
tasks  that  do  not  wish  abort  attempts  from  a  nonpr ivileged 
user's  MCR  or  DCL  abort  command  to  be  allowed,  and  do  not 
otherwise  care  about  the  nature  of  the  abort  attempt.  It  Is 
also  recommended  for  any  nonpr ivileged  tasks  that  simply  do 
not  care  about  the  nature  of  the  abort  attempt. 

After  specifying  a  requested  exit  AST  using  the  SPEAS  form  of 
the  directive,  privileged  tasks  will  enter  the  AST  service 
routine  if  any  of  the  following  abort  attempts  is  made: 


Any  privileged  ABRTS  directive  or  privileged   MCR 
abort  command 


or 


DCL 


•      Any      nonpr ivileged      ABRTS      directive      on      systems      without 
multiuser    protection 


Any  nonpr ivileged    ABRTS    directive    from    the      same 
systems   with  multiuser    protection 


TI: 


on 
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Nonpr iv i leged  tasks  will  enter  the  AST  service  routine  for 
all  of  the  abort  attempts  listed  above,  plus  the  following: 

•  Any  nonpr ivlleged  MCR  or   DCL  abort   command   on   systems 
without  multiuser  protection 

•  Any  nonpr Iv lleged  MCR  or  DCL  abort  command  from   the   same 
TI:   on  systems  with  multiuser  protection 

When  the  AST  service  routine  Is  entered,  the  task's  stack  Is 
in  the  following  state: 

SP+06  -  Event  flag  mask  word 
SP+04  -  PS  of  task  prior  to  AST 
SP+02  -  PC  of  task  prior  to  AST 
SP+00  -  DSW  of  task  prior  to  AST 

No  trap-dependent  parameters  accompany  an  AST  specified  by 
SREAC;  therefore,  the  AST  Service  Exit  directive  can  be 
executed  with  the  stack  in  the  same  state  as  when  the  AST  was 
entered . 

The  event  flao  mask  word  at  the  bottom  of  the  stack  preserves 
the  Walt  For  conditions  of  a  task  prior  to  AST  entry.  A  task 
can,  after  an  AST,  return  to  a  Walt  For  state.  Because  these 
flags  and  other  stack  data  are  in  the  user  task,  they  can  be 
modified.  However,  modifying  the  stack  data  may  cause 
unpredictable  results.  Therefore,  such  modification  is  not 
recommended . 


exit  AST  is  not  specified  for 
to   abort   a   privileged   task 

nonpr 1 V 1 i eg ea  cerminai  using  either  MCR   or   DCL   on 

with  multiuser  protection. 


If  an  SREXS  requested 
It    is    Impossible 


nonpr Ivi leged  terminal  using  either 


a  task , 
from  a 
systems 


■^he  two  forms  of  this  directive  should  not  be  mixed  in  the 
same  code,  since  the  stack  format  and  the  trap-dependent 
parameters  differ.  Any  mismatch  between  the  form  of  the 
directive  and  the  AST  routine  will  have  unpredictable 
results . 

Please  see  Chapter  1  for  a  list  of  restrictions  on  operationji 
that   can   be   performed    in   a    FORTRAN  AST   routine. 
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5.3.74  Send  by  Reference 

The  Send  By  Reference  directive  inserts  a  packet  containing  a 
reference  to  a  region  Into  the  receive-by-ref erence  queue  of  a 
specified  (receiver)  task.  The  Executive  automatically  attaches  the 
receiver  task  for  each  Send  By  Reference  directive  issued  by  the  task 
to  the  specified  region  (the  region  identified  in  W.NRID  of  the  Window 
Definition  Block).  The  attachment  occurs  even  if  the  receiver  ta.sk  is 
already  attached  to  the  region,  unless  bit  WS.NAT  In  W.NSTS  of  the 
Window  Definition  Block  is  set.  The  successful  execution  of  this 
directive  causes  a  significant  event  to  occur. 

The  send  packet  contains: 

•  A  pointer  to  the  created  attachment  descriptor,  which  becomes 
the  region  ID  to  be  used  by  the  receiver  task 

•  The  offset  and  length  words  specified  in  W.NOFF  and  W.NLEN  of 
the  Window  Definition  Block  (which  the  Executive  passes 
without  checking) 

e  i'he  receiver  task's  permitted  access  to  the  region,  contained 
in  the  window  status  word  W.NSTS 

•  The  sender  task  name 

•  Optionally,  the  address  of  an  fl-word  buffer  that  contains 
additional  information  (If  the  packet  does  not  include  a 
buffer  address,  the  Executive  sends  8  words  of  0.) 

The  receiver  task  automatically  has  access  to  the  I'ntlre  region  as 
specified  in  W.NSTS.  The  sender  task  must  be  attached  to  the  region 
with  at  least  the  same  types  of  access.  By  setting  all  the  bits  in 
W.NSTS  to  0,  the  receiver  task  can  default  the  permitted  access  to 
that  of  the  sender  task. 

If  the  directive  specifies  an  event  flag,  the  Executive  sets  the  flag 
in  the  sender  task  --  when  the  receiver  task  acknowledges  the 
issuing   the   Receive   By   Reference  directive   (see 


FORTRAN  Call : 

CALL  SREF  ( tsk , [ ef n ] , i wdb , [ i s rb] [ , Ids] ) 

tsk  =  A  single-precision,  f  loat  I  ng-po  it.t  variable  containing 
the  name  of  the  receiving  task  in  nadlx-50  format 

efn         =      Event    flag    number 

iwdb  =  An  8-word  integer  array  containing  a  Window  Definition 
Block    (see    Section    3.5.2.2) 

isrb  =  An  8-word  Integer  array  containing  additional 
information  (If  specified,  the  address  of  Isrb  is 
placed  in  iwdb(8).  If  Isrb  Is  omitted,  the  contents 
of    iwdb(8)    remain    unchanged.) 

ids        =      Directive    status 
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Macro  Cal 1 : 

SREF$        task,wdb[,efnl 

task      =      Name   of    the    receiver    task 

wdb        =      Window   Definition    Block    address 

efn        =      Event    flag    number 
Macro    Expansion: 

SREF$  ALPHA, WDBADR, 48. 

.BYTE  69., 5  ;SREF$    MACRO    DIG,    DPB    SIZE«5    WORDS 

.RAD50  /ALPHA/  .-RECEIVER    TASK    NAME 

.WORD  48.  .-EVENT    FLAG    NUMBER 

.WORD  WDBADR  -WDB    ADDRESS 

Window   Definition    Block    Parameters: 

Input    parameters: 

Array  Offset 

Element 

iwdb(4)      W.NRID      —      ID  of    the    region    to    be    sent    by    reference 

.       iwdb(5)      W.NOFF      —      Offset    word,    passed    without    checking 

iwdb(6)      W.NLEN      --      Length    word,    passed    without   checking 

iwdb(7)      W.NSTS      --      Bit    settings^    in    window  status    word    (the 

receiver  task's  permitted  access): 


Bit 
WS.RED 
WS.WRT 
WS.EXT 
WS.DEL 


Definition 

1  if  read  access  is  permitted 
1  if  write  access  is  permitted 
1  if  extend  access  is  pe'-mitted 
1  if  delete  access  is  permitted 


iwdb(8)   W.NSRB 


Optional    address   of    an   8-word   buffer 


containing  additional  information 
Output  parameters 

None 
Local  Symbol  Definitions: 

S.RETN   —   Receiver  task  namf  (4) 

S.REBA      —     Window   Definition    Block    base    address    (2) 

S.REEF      —      Event    flag    number    (2) 


1.     If    you      are      a      FORTRAN      programmer,      refer      to      Section      3.5.2      to 
determine    the    bit    values    represented    by   the    symbolic    names   described. 
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DSW  Return  Codes: 

IS. sue   —   Successful  completion. 

lE.UPN  --  A  send  packet  or  an  attachment  descriptor  could  not 
be  al located  . 

IE.  INS  --  The  sender  task  attempted  to  send  a  reference  to  an 
Ancillary  Control  Processor  (ACP)  task,  or  task  not 
instal  led  . 

lE.PRI   —   Specified  access  not  allowed  to  sonder  task  itself. 

lE.NVR   --   Invalid  region  ID. 

lE.IEF  —  Invalid  event  flag  number  (EFN<0,  or  EFN>96  If  group 
global  event  flags  exist  for  the  task;  or  EFN>6'J  if 
not)  . 

lE.HWR  —   Region  had  load  failure  or  parity  error. 

lE.ADP  --  The  address  check  of  tho  DPU,  the  WDB,  or  the  send 
buffer  failed. 

lE.SDP   --   Die  or  DPB  size  Is  Invalid. 

Notes  : 

1.  For  the  user's  convenience,  the  ordering  of  the  SREFS  macro 
arguments  does  not  directly  correspond  to  the  format  of  the 
DPB.  The  arguments  have  been  arranged  so  that  the  optional 
argument  (efn)  Is  at  the  end  of  the  macro  call.  This 
arrangement  is  also  compatible  with  tho  SOAT$  macro. 

2.  Because  region  attachment  requires  system  dynamic  memory,  the 
receiver  task  should  detach  from  any  region  to  which  It  was 
already  attached,  in  order  to  prevent  depletion  of  the  memory 
pool.  That  is,  the  task  needs  to  be  attached  to  a  given 
reg  ion  only  once . 

3.  If  the  specified  event  flag  is  group  global,  then  the  use 
count  for  the  event  flag's  group  is  incremented  to  prevent 
premature  elimination  of  the  event  flags.  The  use  count  Is 
run  down  when: 

•  The  packet  is  received. 

•  The  issuing  task  exits  before  the  packet  Is  received. 
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5.3.7S   Specify  R«eelv«-by-Reference  AST 

The  Specify  Rece Ive-By-Ref erence  AST  directive  Instructs  the  system  to 
record  one  of  the  following  two  cases: 

e  Receive-by-ref erence  ASTs  for  the  Issuing  task  are  desired, 
and  tne  Executive  transfets  jontrol  to  a  specified  address 
when  such  an  AST  occurs. 

e   Receive-by-ref erenc  ASTs  for  the  issulnq  task  are   no   longer 

desl red . 

When  the  directive  spe>jifles  an  AST  service  routine  entry  point, 
receive-by-ref erence  ASTs  for  the  task  will  occur.  The  Executive  will 
transfer  control  to  the  specified  address. 

When  the  directive  omits  an  entry  point  address,  the  Executive  stops 
the  occurrence  of  recelve-by-ref erence  ASTs  for  the  issuing  task. 
Recelve-by-ref erence  ASTs  will  not  occur  until  the  task  issues  another 
Specify  Rece ive-By-Ref erence  AST  directive  that  specifies  an  entry 
point  address.   See  Notes  below. 

FORTRAN  Call : 

Neither  the  FORTRAN  language  -lor  the  ISA  standard  permits  direct 
linking  to  system  trapping  m^'hanlsms;  therefore,  this  directive 
Is  not  available  to  FORTRAN  tasks. 

Macro  Cal 1 : 

SRRAS    (ast) 

ast   =   AST  service  routine  entry  po'nt  address  (0) 

Macro  Expansion: 

SRRA$    RECAST 

.BYTE    21., 2  ;SRRAS  MACRO  DIC,  DPS  SIZE=2  WORDS 

.WORD    RECAST  ;ADDRESS  OF  RECEIVE  AST 

Local  fymbol  Definitions: 

S.RRAE   --   AST  entry  address  (2) 
DSW  Return  Codes: 

IS. sue   --   Successful  completion. 

lE.UPN   --   Insufficient  dynamic  memory. 

IE. ITS   --   AST  entry  point  address  is  already  unspecified. 

IE. AST   --   Directive  wis  issue)  from  an    AST  service  routine,   or 
ASTs  nre   disabled. 

IF.ADP   —   Part  of  the  DPS  is  out  of  the  issuing  task's   address 
space . 

lE.SDP   --   DIC  or  DPS  size  is  invalid. 
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Notes : 

1.  Specify  Receive-By-Reference  AST  requires  dynamic  memory. 

2.  The  Executive  queues  recelve-by-ref erence  ASTs  when  a  message 
is  sent  to  the  task.  Future  receive-by-ref erence  ASTs  will 
not  be  queued  for  the  task  until  the  first  one  queued  has 
been  effected. 

3.  The  task  enters  the  receive-by-ref erence  AST  service  routine 
with  the  task  stack  in  the  following  state: 

SP+06  -  Event  flag  mask  word 
SP+04  -  PS  of  task  prior  to  AST 
SP+02  -  PC  of  task  prior  to  AST 
SP+00  -  DSW  of  task  prior  to  AST 

No  trap-dependent  parameters  accompany  a  receive-by-ref erence 
AST;  therefore,  the  AST  Service  Exit  directive  (see  Sect'on 
5.3.4)  must  be  executed  with  the  stack  in  the  same  state  as 
when  the  AST  was  effected. 

4.  This  directive  cannot  be  issued  either  from  an  AST  service 
routine  or  when  ASTs  are  disabled. 
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STAF$ 


5.3.76  S«t  Affinity 

The  Set  Affinity  directive  can  be  issued  by  a  task  to  select  which  CPU 
and  UNIBUS  run(s)  to  use  during  task  execution.  This  directive  can 
only  be  Issued  for  RSX-llH-PLUS  tasks  that  are  executed  on  PDP-11 
multiprocessor  systems. 

Task  CPU/UNIBUS  affinity  enables  a  task  to  select  which  CPU  and  UNIBUS 
run(s)  to  use  for  task  execution  when  running  on  PDP-11  multiprocessor 
systems.  The  programmer  must  be  completely  aware  of  the  particular 
system  hardware  configuration  in  which  the  task  will  bo  executed 
before  using  these  directives. 

Task  CPU/UNIBUS  affinity  can  be  established  at  three  possible  times: 

1.  When  the  task  is  installed 

2.  Whrtn  the  task  is  mapped  into  a  device  partition   (which   must 
have    C»^U/UNIBUS  run  affinity  previously  established) 

3.  When  ser  by  the  Set  Affinity  directive 

When  issued,  the  Set  Affinity  directive  produces  an  «iffinity  mask  word 
that  defines  task  CPU/UNIBUS  affinity.  One  bit  in  the  word  is  set  to 
select  one  CPU  on  which  the  task  will  be  run.  One  or  more  of  17 
additional  bits  can  be  set  to  select  one  or  more  UNIBUS  runs  for 
peripheral  device  use  during  task  execution. 

Two  directives  support  task  affinity,  as  follows: 

•  Set  Affinity  -  This  directive  accepts  parameters  that  define 
the  Ci^U  and  UNIBUS  run  mask  for  task  execution.  At  assembly 
time  a  1-word  mask  is  created  consisting  of  the  logical  OR  of 
all  the  parameters. 

•  Remove  Affinity  -  This  directive  removes  task  CPU/UNIBUS 
affinity  previously  established  by  a  Set  Affinity  directive. 

A  1-word  CPU/UNIBUS  affinity  mask  defines  directive  parameters. 
Parameters  enable  specification  of  one  of  four  (maximum)  CPUs  and  one 
or  more  of  twelve  (maximum)  UNIBUS  runs.  The  affinity  mosk  word 
consists  of  the  logical  OR  of  all  the  parameters.  Only  one  parameter 
(cp  or  ub)  is  required.  Directive  parameters  are  assembled  to  produce 
the  mask  word  bit  values  shown  as  follows: 

Aas cabled 
Bit  Value 

1 
2 
4 

10 

20 

40 

100 

200 


Directive 

Parameter 

Mask  Word  Function 

CPA 

Select  CPU  "A" 

CPB 

Select  CPU  "B" 

CPC 

Select  CPU  "C" 

CPD 

Select  CPU  "D" 

UBE 

Select  UNIBUS  run  " E" 

UBF 

Select  UNIBUS  run  T" 

UBH 

Select  UNIBUS  run  "H" 

UBJ 

Select  UNIBUS  run  "J" 
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Directive  Assembled  "^ 

Parameter         Mask  Word  Function  Bit  Value 

UBK  Select  UNIBUS  run  "K"  400 

UBL  Select  UNIBUS  run  " L"  1000 

UBM  Select  UNIBUS  run  "M"  2000 

UBN  Select  UNIBUS  run  "N"  4000 

UBP  Select  UNIBUS  run  "P"  10000 

UBR  Select  UNIBUS  run  "R"  20000 

UBS  Select  UNIBUS  run  "S"  40000 

UBT  Select  UNIBUS  run  "T"  100000 

FORTRAN  Call : 

CALL  STAF  (iaff [,ids] ) 

iaff  «  Affinity  mask  word 

ids   ■   Integer  to  receive  Directive  Status  Word 

Macro  Call : 

STAP$  fcplublub.. . ) 

cp     =     CPU  selected    (A  through   D,    as   previously  listed) 

ub     «      UNIBUS    run   selected    (E   through  T,    as   previously   listed) 

Macro    Expansion: 

STAF$         CPB!UBF!UBJ 

.BYTE         161., 2  ;STAF$    MACRO   DIC,    DPB    SIZE-2   WORDS 

.WORD         242  ;    AFFINITY   MASK   WORD    ('OR*    OF    PARAMETERS) 

Local    Symbol    Definitions: 

S.AFAF      —      Affinity  mask   word    (2) 
DSW   Return    Codes: 

IS. sue   •--   Successful  completion. 

IE. ITS   —  Task  installed  with  affinity  . 

lE.ADP  —  Part  of  the  DPB  is  out  of  the  issuing  task's  address 
space . 

IE. SOP   —   DIC  or  DPB  size  is  invalid. 

Notes: 

1.  A  task  that  is  installed  with  task  affinity  must  not  issue 
this  directive.  Any  attempt  to  do  so  results  in  an  IE. ITS 
error  returned. 

2.  If  this  directive  is  issued  with  parameters  that  prevent  the 
task  from  running,  an  IE. ITS  error  is  returned. 
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STIM$ 


5.3.77   Set  System  Tine  Directive 

The  Set  System  Time  directive  instructs  the  system  to  set  the  sytl^«M'a 
internal  time  to  the  specified  time  parameters.  Optionally,  the  Set 
System  Time  directive  returns  the  system's  current  Internal  time  to 
the  issuing  task  before  settlnq  It  to  the  specified  values. 

All  time  parameters  must  be  specified  as  binary  numbers. 

A  task  must  be  privileged  to  issue  this  directive. 

When  this  directive  changes  the  system  time  by  a  specified  amount,  It 
also  effectively  changes  the  time  of  anything  resident  on  the  clock 
queue  by  the  same  amount.  Thus,  the  time  synchronization  of  events  Is 
maintained . 

FORTRAN  Call : 

CALL  SETTIM  (  Ibuf n [ , 1 buf p[ , ids]] ) 


ibufn   =   An  8-word  Integer  array 
buffer 


new  time  specification 


An  8-word  integer  array  --  previous  time  buffer 
Directive  status 


ibufp 

ids 

Macro  Cal 1 : 

STIMS  bufn, [bufp) 

bufn   =   Address  of  8-word  new  time  specification  buffer 

bufp   =   Address  of  8-word  buffer  to  receive  the 
previous  system  time  parameters 

Buffer  Format: 

Word  0   - 

Word  1   - 

Word  2   - 


Word  3 
Word  4 
Word  5 


Year  (since  1900) . 

Month  (1-12) . 

Day  (1-n,  where  n  is  the  highest  day  possible  for  the 
given  month  and  year). 

Hour  (0-23) . 

Minute  (0-59) . 

Second  (0-59) . 


Word  6  --  Tick  of  second  (0-n,  where  n  is  the  frequency  of  the 
system  clock  minus  one).  If  the  next  parameter 
(ticks  per  second)  is  defaulted,  this  parameter  Is 
ignored  . 

Word  7  --  Ticks  per  second  (must  be  defaulted  or  must  match  the 
frequency  of  the  system  clock).  This  parameter  is 
used  to  verify  the  intended  granularity  of  the  "tick 
of  second"  parameter. 
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NOTE 

If  any  of  the  specified  new  time 
parameters  are  defaulted  (equal  to  -1), 
the  corresponding  previous  system  rime 
parameters  will  temaln  unchanged  and 
will  be  substituted  for  the  defaulted 
parameters   during    argument    validation. 


Macro    Expansion: 

STIMS  NEWTIM.OLDTIM 

.BYTE  61.  ,3 

.WORD  NEWTIM 

.WORD  OLDTIM 


;STIM$    Die,     DPB    SI/TE-l    WORDS 
;ADDRESS    OF    8. -WORD    INPUT    BUFFER 
.-ADDRESS    OF    8. -WORD    OUTPUT    BUFFER 


Local    Symbol    Definitions: 

S.TIBA      —      Input    buffer    address    (2) 

S.TIBO      —      Output    buffer    address    (2) 

The    following    offsets    are    assigned    relative    to    the    start    of    each      time 
parameters    buffer: 

S.TIYR  —  Year    (2) 

S.TIMO  --  Month    (2) 

S.TIDA  --  Day    (2) 

S.TIHR  --  Hour    (2) 

S.TIMI  --  Minute  (2) 

S.TICS  --  Second  (2) 

S.TICT  —  Clock  tick  of  second  (2) 

S.TICP  —  Clock    ticks    per    second    (2) 

DSW  Return  codes: 

IS. sue  --  Successf'il  completion. 

TE.PRI  —  The  issuing  task  is  not  privileged. 

lE.ITI  —  One  of  the  specified  time  parameters  is  out  of  range, 
or  both  the  t  Ick-of-second  p.irameter  and  the 
t Icks-per-second  parameter  were  specified  and  the 
t icks-per-second  parameter  does  not  match  the 
system's  clock  freqL.ency.  The  system  time  at  the 
moment  the  directive  Is  Issued  (returned  In  the 
second  buffer)  can  be  useful  In  determining  the  cause 
of  the  fault  if  any  of  the  specified  time  parameters 
were  default ed. 

lE.ADP  —  Part  of  the  DPB  or  one  of  the  buffers  is  out  of  the 
issuing  task's  address  Tpace. 

-     lE.SDP   —   Die  or  DPB  size  is  invalid. 
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Notes ! 


1.  Execution  of  tMs  directive  qenerates  nn  Error  Loq  packet  and 
sends  it  to  the  Error  Loqqinq  subsystem. 

2.  On  an  RSX-llM-PLUS  system  with  accounting  active,  this 
directive  causes  an  accounting  transaction  that  records  both 
the  old  and  new  time. 

3.  The  hiqhest  clock  frequency  supported  by  the  operating  system 
is  1000  hz  for  a  programmable  clock.  Note  that  as  the  clock 
frequency  approaches  this  value,  the  maximum  resolution  for 
this  directive  becomes  more  time  critical.  The  accuracy  of 
this  directive  depends  upon  the  elapsed  time  between  the 
moment  that  a  new  system  time  Is  specified  and  the  time  that 
the  directive  actually  traps  to  the  Executive. 

4.  The  buffers  used  in  this  directive  are  compatible  with  those 
of  the  Get  Time  Parameters  (GTIMS)  directive. 

5.  Tne  second  buffer  (previous  time)  Is  only  filled  In  If  the 
directive  was  successfully  executed  or  if  it  was  rejected 
with  an  error  code  of  lE.ITI. 
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STLO$ 

5.3.78      Stop    For    Logical    OR   Of    Event    Flaqs 

The  Stop  For  Logical  OR  Of  Event  Flags  directive  Instructs  the  system 
to  stop  the  issuing  task  until  the  Executive  sets  one  or  more  of  the 
indicated    event    flags    from    one    of    the    following    groups: 

GR    0  --  Local    flags    1-16 

GR    1  --  Local     flags    17-32 

GR    2  --  Common    flags    33-48 

GR    3  --  Common    flags    49-64 

GR    4  —  Group   global    fligs    6S-80 

GR    5  —  Group  global    flags    81-96 

The  task  does  not  stop  itself  if  any  of  the  indicated  flags  are 
already  set  when  the  task  issues  the  directive.  This  directive  cannot 
be    issLied    at    AST    state. 

A    task    that    is  stopped    for    one    or    more  event       flags      can      only  become 

unstopped      by  setting       the      specified  event       flag;       it    cannot  become 

unstopped  with  the  Unstop  directive  or  the  MCR  Unstop  or  DCL  START 
command . 

FORTRAN    Call : 

CALL    STLOR     ( ief 1 , I e f 2, i e f 3,     ...       ief(n)) 

lefl    ...    i«»f(n)       =      List    of    event    flag    numbers 
Macro    Cal 1  : 

STLO$         grp,    msk 

grp      «      Desired    group  of    event    flags 
msk      =•      A    16-bit    mask    word 
Macro    Expansion: 

STLOS  1,47 

.BYTE  I  37.,  3  ;STLO$    MACRO    DIC,     DPB    SIZE-3    WORDi: 

■WORD  1  ;GROUP    1    FLAGS     (FLAGS     17-32) 

•WORD  47  ;MASK   WORD    =    47     (FLAGS     17,     18,     19,     22) 

Local    Symbol    Definitions: 

S.TLGR      --      ':;roup    flags    (2) 
S.TLMS      --      Mask    word     (2) 
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DSW  Return  Codes: 

IS. sue   --  Successful  completion. 

IE. AST   —  The  issuing  task  is  at  AST  state. 

lE.IEF   —  An   event   flag   group  other   than   0   thru   5   was 
specified,  or  the  event  flag  mask  word  is  zero. 

lE.ADP   —  Part  of  the  DPB  is  out  of  the  issuing  task's   address 
space. 

lE.SDP   —  DIG  or  DPB  size  is  invalid. 

Notes : 

1.  There  is  a  one-to-one  correspondence  between  bits  in  the  mask 
word  and  the  event  flags  in  the  specified  group.  That  is,  if 
group  1  were  specified  (as  in  the  above  macro  expansion 
example),  bi:  0  in  the  mask  word  would  correspond  to  event 
flag  17,  bit  1  to  event  flag  18,  and  so  forth. 

2.  The  Executive  does  not  arbitrarily  clear  event  flags  when 
Stop  For  Logical  OR  Of  Event  Flags  conditions  are  met.  Some 
directives  (Queue  I/O  Request,  for  example)  implicitly  clear 
a  flag;  otherwise,  they  must  be  explicitly  cleared  by  a 
Clear  Event  Flag  directive. 

3.  The  argument  list  specified  In  the  FORTRAN  call  must  contain 
only  event  flag  numbers  that  lie  within  one  event  flag  group. 
If  event  flag  numbers  are  specified  that  lie  in  more  than  one 
group,  or  If  an  invalid  event  flag  number  is  specified,  a 
fatal  FORTRAN  error  Is  generated. 

4.  Tasks  stopped  for  event  flag  conditions  cannot  be  unstopped 
by  issuing  the  Unstop  directive;  tasks  stopped  in  this 
manner  can  only  be  unstopped  by  meeting  event  flag 
cond Itions. 

^*  The  grp  operand  must  always  be  of  the  form  n  regardless  of 
the  macro  form  used.  In  all  other  macro  calls,  numeric  or 
address  values  for  $S  form  macros  have  the  form: 

In 

For  STLO$S  this  form  of  the  grp  argument  would  be: 

n 

6.      If    the    st^eclfled      event  flag      group      is      group     global,      the 

group's        use      count      Is  Incremented      to      prevent      premature 

elimination   of    tue    event  flags.      The    use   count      Is      run      down 
when: 

•  The    Stop   For    condition    is    satisfied. 

•  The    issuing    task   exits   before    the    Stop      For      condition      is 
satisfied . 
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STOP$S 


5.3.79   Stop  ($S  Form  Recommended) 


The  Stop  directive  stops  the  issuing  task.  This  directive  cannot  be 
issued  at  AST  state.  A  task  stoppeci  in  this  manner  can  only  bo 
unstopped  by:  another  task  that  issues  an  Unstop  directive  directed 
to  this  task;  this  task  issuing  an  Unstop  directive  at  AST  state;  or 
the  MCR  Unstop  or  DCL  START  command. 

FORTRAN  Call : 

CALL  STOP  ([ids] ) 

ids    =»   Integer  to  receive  the  directive  status  word 
Macro  Cal 1  : 

STOPSS 
Macro  Expansion: 

STOP$S 


MOV 

.BYTE 

EMT 


(PC)+,-(SP) 
131. ,1 
377 


PUSH  DPB  ONTO  THE  STACK 

STOPS  MACRO  DIG,  DPB  SIZE=l  WORD 

TRAP  TO  THE  EXECUTIVE 


Local  Symbol  Definitions: 

None 
DSW  Return  Codes: 

IS. SET   —  Successful  completion. 

The  issuing  task  is  at  AST  state 


IE. AST 
lE.ADP 


—      Part   of    the    DPB    is   out    of    the    issuing    task's      address 
space . 


lE.SDP      —     Die   or    DPB    size    is    invalid 
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STSE$ 


5. J. 80   Stop  Por  Single  Event  Flag 

The  Stop  For  Single  Event  Flag  directive  Instructs  the  system  to  stop 
the  issuing  task  until  the  specified  event  flag  is  set.  If  the  flag 
is  set  at  issuance,  the  task  is  not  stopped.  This  directive  can  not 
be  issued  at  the  AST  state. 

A  task  that  is  stopped  for  one  or  more  event   flags   can   only  become 

unstopped   by   setting   the   specified   event   flag;   It  cannot  become 

unstopped  by  the  Unstop  directive  or  the  MCR  Unstop  or  DCL  START 
command . 

FORTRAN  Call  : 

CALL  STOPFR  ( i ef n  [  ,  Id.l)  ) 

lefn   =   Event  flag  number 


Ids 
Macro  Cal 1  : 
STSE$ 
efn 


=   Integer  to  receive  directive  status  word 

efn 
=   Event  flag  number 


Macro  Expansion: 


STSES 
.BYTE 
.WORD 


7 

135. ,2 

7 


;STSE$    MACRO    DIC,    UPB    SIZE=2    WORDS 
; LOCAL    EVENT    FLAG    NUMBER    =    7 


Local    Symbol    Definitions: 

S.TSEF      —      Event    flag    number    (2) 
DSW   Return    Codes: 

IS. sue   --   Successful  completion. 

The  issuing  task  is  at    AST  state, 


IE. AST 
IE. lEF 

lE.ADP 
lE.SDP 


Invalid  event  flag  number  (EFN<1,  or  EFN>96  if  group 
global  event  flags  exist  for  the  task's  group;  or 
EFN>64    if    not)  . 

Part  of  the  DPB  is  out  of  the  issuing  task's  address 
space. 

DIC   or    DPB    size    is    invalid. 


Note: 


If  the  specified  event  flag  is  group  global,  the  use  count  for 
the  event  flag's  group  is  incremented  to  prevent  premature 
elimination   of   event    flags.      The    use   count    is    run   down    when: 

•  The    Stop    For    condition    is    satisfied. 

•  The    issuing    task      exits      before      the      Stop      For      condition      is 
sat  isf led  . 
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SVDB$ 


5.3.81   Specify  SST  Vector  Table  For  Debugging  Aid 

The  Specify  SST  Vector  Table  For  Debugging  Aid  directive  Instructs  the 
system  to  record  the  address  of  a  table  of  SST  service  routine  entry 
points  for  use  by  an  Intratask  debugging  aid  (ODT,  for  example). 

To  deasslgn  the  vector  table,  omit  the  parameters  adr  and  len  from  the 
macro  cal 1 . 

Whenever  an  SST  service  routine  entry  Is  specified  in  both  the  table 
used  by  the  task  and  the  table  used  by  a  debugging  aid,  the  trap 
occurs  for  the  debugging  aid,  not  for  the  task. 

FORTRAN  Call : 

Neither  the  FORTRAN  language  nor  the  ISA  standard  permits  direct 
linking  to  system  trapping  mechanisms;  therefore,  this  directive 
Is  not  available  to  FORTRAN  tasks. 

Macro  Cal 1 : 

SVDB$         [adr]  [,len] 

adr   =   Address  >f    SST  vector  table 

len   =   Length  of  (that  is,  number  of  entries  In)  the  table   In 
words 

The  vector  table  has  the  following  format: 

Word  0  --  Odd  address  of  nonexistent  memory  error 

Word  1  --  Memory  protect  violation 

Word    2  —  T-blt    trap  or    execution   of   a    BPT    instruction 

Word    3  --  Execution    of    an    TOT    instruction 

Word    4  --  Execution    of    a    reserved    instruction 

Word    5  --  Execution   of    a    non-RSX    EMT    instruction 

Word    6  —  Execution    of    a    TRAP    instruction 

Word    7  --  PDP-11/40    floating-point    exception 

A  0  entry  In  the  table  Indicates  that  the  task  does  not  want  to 
process    the   corresponding    SST. 

Macro    Expansion: 


SVDB$  SSTTBL,4 

.BYTE  103. ,3 

.WORD  SSTTBL 

.WORD  4 


SVDBS    MACRO    DIG,     DPB    SIZE=3    WORDS 
ADDRESS    OF    SST    TABLE 
SST    TABLE    LENGTH=4    WORDS 
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Local  Symbol  Definitional 

S.VDTA   --   Table  address  (2) 

S.VDTL   --   Table  length  (2) 
DSW  Return  Codes: 

IS. sue   —   Successful  completion. 

lE.ADP   —   Part  of  the  DPB  or  table  is  o  it  of  the  issuing  task'; 
address  space. 

lE.SDP   --   Die  01  DPB  size  is  Invalid. 
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5.3.82   Specify  SST  Vector  Table  For  Task         ^ 

The  Specify  SST  Vector  Table  For  Task  directive  Instructs  the  system 
to  record  the  address  of  a  table  of  SST  service  routine  .«ntry  points 
for  use  by  the  Issuing  task. 

To  deasslgn  the  vector  table,  omit  the  parameters  adt  and  len  from  the 
macro  cal  1  . 

Whenever  an  SST  service  routine  entry  Is  specified  In  both  the  table 
used  by  the  task  and  the  table  used  by  a  debuqqinq  .ild,  the  trap 
occurs  for  the  debugging  aid,  not  for  the  task. 

FORTRAN  Cal 1 : 

Neither  the  FORTRAN  lanquaje  nor  the  ISA  standard  permits  direct 
linking  to  system  trapping  mechanism;  therefore,  this  directive 
Is  not  available  to  FORTRAN  tasks. 

Macro  Cal 1 : 

SVTKS         (adrl  [,lenl 

adr      =      Address   of    SST   vector    table 

len      =      Length   of    (that    is,    number    of    entries    in)    the    table      in 
words 

The    vector    table    has    the    following    format: 

Wotd       0      --       Vld    address    of    nonexistent    memory   error 

Memory    protect    violation 

T-bit    trap  or    execution    of   a    BPT    instruction 

Execution  of  an  TOT  instruction 

Execution  of  a  reserved  Instruction 

Execution  of  a  non-RSX  EMT  instruction 

Execution  of  a  TRAP  instruction 

Word   7   --   PDP-ll/40  floating-point  exception 

A  0  entry  in  the  table  Indicates  that  the  task  does  not  want  to 
process  the  corresponding  SST. 

Macro  Expansion: 

svTK$   s;:;ttbl,4 

.BYTE  105.,  3  ;SVTK$    MACRO    DIC,    DPB    :;iZE=3    WORDS 

.WORD         SSTTBL  ; ADDRESS    OF    SST    TABLE 

•WORD  4  ;5ET    TABLE    LENGTH=4    WORDS 


Word 

1 

Word 

2 

Word 

3 

Word 

4 

Word 

5 

Word 

6 
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Local    Symbol    Definitions: 

S.VTTA      --      Table   address    (2) 

S.VTTL      —      Table    length    (2) 
DSW    Return    Codes: 

IS. sue   —   Succesafjl  completion. 

lE.ADP   --   Part  of  the  DPB  or  table  is  out  of  the  Issuing  task's 
address  space. 

lE.SDP   --   DIG  or  DPD  size  is  invalid. 


» 
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ULGF$ 

5.3.83   Unlock  Group  Global  Event  Flags  ($S  Form  RecoBmendef*) 

The  Unlock  Group  Global  Ev^nt  Flag?  directive  Instructs  the  Executive 
to  decrement  the  use  count  cf  the  group  global  event  flags  for  the 
issuing  task's  protection  group  UIC  ;H.CUIC+1).  This  unlocks  flags 
that  were  locked  by  the  Create  Group  Global  Event  Flags  directive. 

A  task  may  only  unlock  the  event  flags  once  before  locking  them  again. 

The  group  global  event  flags  are  eliminated  if  the  following  two 
conditions  are  satisfied: 

•  The  use  count  in  the  group  global   tvent   flag   control   block 
(GFB)  is  zero  after  this  directive  is  issued. 

•  The  GFB  is  marked  for  deletion. 
FORTRAN  Call : 

CALL  ULGF  ( ( ids] ) 

ids   =   Directive  status 

Macro  Call : 

ULGF$S    ferr] 

err   =   Error  routine  address 

Macro  Expansion: 

ULGFSS  ERR 

MOV  (PC)+,-(SP)  ;P"JSH  DPB  ONTO  THE  STACK 

.BYTE  159., 1  ;DIC  =  159.,  DPB  SIZE=  1  WCr!D 

EMT  377  ;TRAP  TO  THE  EXECUTIVE 

BCC  .+6  .-BRANCH  IF  DIRECTIVE  SUCCESSFUL 

JSR  PC, ERR  /OTHERWISE,  CALL  ROUTINE  "ERR" 

Local    Symbol    Definitions: 

None . 
DSW    Return    Codes: 

IS. sue      --     Successful    completion. 

lE.RSU      —      Event    flags   already   unlocked    from    the    issuing    task. 

lE.ADP      —      Part   of    the    DPB    is   out    of    the    issuing    task's      address 
space. 

lE.SDP      —      Die    or    DPB    size    is    invalid. 
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5.3.84   Unmap  Address  Window 

The  Unm.ip  Address  Window  directive  unmapy  a  specified  window.  After 
the  window  has  been  unmapped,  references  to  the  corresponding  virtual 
addresses  are  invalid  and  caur.e  a  processor  trap  to  ojcur . 

FORTRAN  Call  : 

CALL  UNMAP  (lwdb[,ids] ) 

iwdb   =   An  8-word  Integer  array  cont^ilnlng  a   Window  Definition 
Block  (see  Section  3.5.2.2) 

ids    =   Directive  status 
Macro  Cal  1  : 

UMAP$   wdb 

wdb   =   Window  Definition  Block  addre.ss 
Macro  Expansion: 

UMAP$    WDBADR 

.BYTE    123.,  2  ;UMAP$  MACRO  DIG,  DPS  SI7.E  =  2  WORDS 

.WORD    WDBADR  ;WDB  ADDRESS 

Window  Definition  Block  Parameters: 

Input  parameters: 

Array      Offset 
Element 

iwdb(l)     W.NID   —   ID  of  the  window  to  be  unmapped 
bits  0-7 

Output  parameters 

iwdb(7)     W.NSTS   —   Bit  settings!  in  the  windov  status  word: 

Bit  Definition 


WS.UNM      1    if    the     window 
successfully  unmapped 

Local  Symbol  Definitions: 

U.MABA   —   Window  Definition  Block  address  (2) 


was 


1.  If  you   are   a   FORTRAN   programmer,   refer   to   Section   3.5.2   to 
determine  the  bit  values  represented  by  the  symbolic  names  described. 


5-207 


DIRECTIVE    DESCRIPTIONS 

DSW   Return    Codes: 

IS. sue      —      Successful    completion. 

IE. ITS      —      The    specified    address    window    is   not    mapped. 

lE.NVW      --      Invalid    address   window    ID. 

lE.ADP      —      DPB    or    WDB    out    of    range. 

lE.SDP      —      Die   or    D.>B    size    Is    invalid. 


• 
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5. 3.85  Unstop  Task 

The  Unstop  Task  directive  unstops  the  specified  task  that  has  stopped 
itself  by  either  the  Stop  or  the  Receive  Data  Or  Stop  directive.  It 
does  not  unstop  tasks  stopped  for  event  flag (a)  or  tasks  stopped  for 
buffered  I/O.  If  the  Unstop  directive  Is  issued  to  a  task  previously 
stopped  by  means  of  the  Stop  or  Receive  Or  Stop  directive  while  at 
task  state,  and  the  task  is  presently  at  AST  state,  thj  task  only 
becomes  unstopped  when  it  returns  to  task  state. 

It  is  considered  the  responsibility  of  the  unstopped  task  to  determine 
if  it  has  been  validly  unstopped. 

The  Unstop  directive  does  not  cause  a  significant  event. 

FORTRAN  Call : 

CALL  USTP  (rtname[ ,idsl ) 

rtname   =   Name  of  task  to  be  unstopped 

ids      =   Integer  to  receive  directive  status  information 

Macro  Cal 1  : 

USTP$    tname 

tname   =   Name  of  task  to  be  unstopped 

Macro  Expansion: 

USTP$    ALPHA 

•BYTE    133., 3  ;USTP$  MACRO  DIG,  DPB  SIZE=3  WORDS 

.RAD50   /ALPHA/  ;NAME  OF  TASK  TO  BE  UNSTOPPED 

Local  Symbol  Definitions: 

U.STTN   --   Task  name  (4) 
DSW  Return  Codes: 

IS. sue   —   Successful  completion. 

IE.  INS   —   The  specified  task  is  not  installed  in  the  system. 

IE. ACT   --   The  specified  task  is  not  active. 

IE. ITS   —   The  specified  task  is  not  stopped,  or  it   is   stopped 
for  event  flag(s)  or  buffered  I/O. 

lE.ADP   —   Part  of  the  DPB  is  out  of  the  issuing  task's   address 
space . 

lE.SDP   —   Die  or  DPB  size  is  invalid. 


5-209 


DIRECTIVE  DESCRIPTIONS 

VRCD$ 

5.3.86  Variable  Receive  Data 

The  Variable  Receive  Data  directive  instructs  the  system  to  dequeue  a 
variable-length  data  block  £or  the  issuing  task;  the  data  block  has 
been  queued  (FIFO)  for  the  task  by  a  Variable  Send  Data  directive. 
When  a  sender  task  is  speciCied«  only  data  sent  by  the  specified  task 
is  received. 

Buffer  size  can  be  256.  words  maximum.  If  no  buffer  size  is 
specified,  the  buffer  size  Is  13.  words.  If  a  buffer  size  greater 
than  256.   Is  specified,  an  IE. IBS  error  is  returned. 

A  2-word  sender  task  name  (In  Radlx-bO  form)  and  the  data  block  are 
returned  In  the  specified  buffer,  with  the  task  name  in  the  first  two 
words.  For  this  reason,  the  storage  you  allocate  within  the  buffer 
should  be  two  words  greater  than  the  size  of  the  data  portion  of  the 
message  specified  in  the  directive. 

Var if ble-length  data  blocks  are  transferred  from  the  sending  task  to 
the  receiving  task  by  means  of  buffers  in  the  secondary  pool. 

FORTRAN  Call: 

CALL  VRCD  ( [task] ,bufadr, [buflenlt, ids]) 

task   =■   Sender  task  name 

buf    ==  Address  of  buffer  to  receive  the  sender  task  name  and 
data 

buflen  =   Length  of  buffer 

ids    =   Integer  to  receive  the  directive  status  word. 

If  the  directive  was  successful.  It  returns  the  number  of  words 
transferred  into  the  user  buffer.  If  the  directive  execution 
encountered  an  error,  it  returns  the  error  code  in  the  ids 
parameter. 

Any  error  return  of  the  form  IE. XXX  Is  a  negative  word  value.  If 
the  status  is  positive,  the  value  of  the  status  word  is  the 
number  of  words  transferred  including  the  taskname.  For  example, 
if  you  specify  a  buffer  size  of  13  in  the  VRCD$  call,  the  value 
returned  in  the  directive  status  word  Is  15  (13  words  of  data 
plus  the  two  words  needed  to  return  the  taskname) . 

Macro  Call : 

VRCD$     [task] ,bufadr[ , buflen] 

task  =   Sender  task  name 

bufadr  =      Buffer   address 

buflen  =      Buffer    size    in   words 
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Macro  Expansions 

VRCD$  SNDTSK,DATBUF,BUPSIZ 

.BYTE  75., 6  ;VRCD$   MACRO   DIC,    DPB    SIZE-6   WORDS 

.RAD50  /SNDTSK/  /SENDER    TASK    NAME 

.WORD  DATBUF  ;ADDRESS    OF    DATA    BUFFER 

.WORD  BUPSIZ  ;BUPPER    SIZE 

Local    Symbol  Definitions: 

R.VDTN  —      Sender    task   name    (4) 

R.VDBA  —     Buffer   address    (2) 

R.VDBL  —      Buffer    length    (2) 

R.VDTI  —      Reserved    (2) 
DSW  Return   Codes: 

IS. sue  —      Successful    completion. 

IE. INS  —      Specified    task   not    installed. 

IB. ITS  —     No   data    in    task's   receive   queue. 

lE.RBS  —     Receive  buffer    is    too    small. 

IE. IBS  —      Invalid   buffer    size    specified    (greater    than    255.) 

lE.ADP      —      Part   of    the    DPB   or    buffer    is   out   of    the    issuing 
task's    address    space. 

IE. SOP      —      DIC  or    DPB   size    Is    invalid. 


5-211 


DIRCCTIVr  DESCRIPTIONS 

VRCS$ 


When  a  sender  task  Is  specified,  only  data  sent  by  the  specified  task 
is  received. 

Buffer  size  can  be  256.  words  maximum.  If  no  buffer  size  is 
specified,  the  buffer  size  is  13.  words.  If  a  buffer  aizf  greater 
than  256.   is  specified,  an  IE.  IBS  error  is  returned. 

A  2-word  sender  task  name  (in  Radix -50  form;  and  the  .lata  block  are 
returned  In  th.»  specified  buffer,  with  the  task  name  in  the  first  2 
words.  For  this  reason,  the  storage  you  allocate  within  the  buffer 
should  be  two  words  greater  than  the  size  of  the  data  portion  of  the 
message  specified  in  the  directive. 

Variable-length  data  blocks  are  transferred  from  the  sending  task  to 
the  receiving  task  by  means  of  buffers  in  the  secondary  p'^ol  . 

FORTRAN  Call : 

CALL  VRCS  ([task] ,bufadr, [buflen]  r, ids! ) 

task   =   Sender  task  name 

buf    »   Address  of  buffer  to  receive  the  sender  task  nam*?  and 
data 

buflen  =   Length  of  buffer 

ids    =   Integer  to  receive  the  directive  status  word 

Tf  the  directive  was  successful,  it  returns  the  nuinbei  of   words 

transferred   into   the   user   buffer.   If  the  directive  execution 

encountered  an  error,  it  returns  the  error  code  in  the  ids 
parameter . 

Any  error  return  of  the  form  IE. XXX  is  a  negative  word  value.  If 
the  status  Is  positive,  the  value  of  the  status  word  Is  the 
number  of  words  transferred  Including  the  taskname.  For  example, 
if  yo'j  specify  a  buffer  size  of  13  In  the  VRCSS  call,  the  va^ue 
returned  in  the  directive  status  word  is  15  (13  words  of  data 
plus  the  two  words  needed  to  return  the  taskname) . 
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Macro  Cal 1 : 

VRCS$  [♦•ask]  ,bufadr[  ,buflenl 

task        ■      Sender    task  name 

bufadr   ■     Buffer    address 

'  buflen   =      Buffer    size    in  words 

Macro    Expansioni 

VRCS$  SNDTSK,DATBUF,BUFSIZ 

.BYTE  139., 6  ;VRCS$    MACRO    DIC,    DPD    SIZE-6    WORDS 

.RAD50  /SNDTSK/  ;SENDER    TASK   NAME 

.WORD  DATBUF  ;ADDRESC    OF    DATA    BUFFER 

•WORD  BUFSIZ  /BUFFER    SIZE 

Local    Symbol  Definitions: 

R.VSTN  —      Sender    task   name    (4) 

R.VSBA  —      Buffer    address    (2) 

R.VSBL  —   Buffer  length  (2) 

R.VSTI  ~   Reserved  (2) 
DSW  Return  Codes: 

IS. sue  —   Successful  completion. 

IE. INS  —   Specified  task  not  installed. 

lE.RBS  —   Receive  buffer  is  too  small. 

IE. IBS  — ■   Invalid  buffer  size  specified  {greater  than  255.) 

lE.ADP   —   Part  of  the  DPB  or  buffer  is  out  of  the  issuing 
task's  address  space. 

lE.SDP   —   DIC  or  DPB  size  is  invalid. 
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5.3.88  Variable  Receive  Date  Or  Exit 

The  Variable  Receive  Ojta  Or  Exit  directive  Instructs  the  system  to 
dequeue  a  variable-length  data  block  for  the  issuing  task;  the  data 
block  has  been  queued  (FIFO)  for  the  task  by  a  Variable  Send  Data 
directive.  When  a  sender  task  Is  specified,  only  data  sent  by  the 
specified  task  is  received. 

A  2-word  sender  task  name  (in  Radix-50  form)  and  tha  data  block  are 
returned  In  the  specified  buffer,  with  the  task  name  In  the  first  2 
words.  For  this  reason,  the  storage  you  allocate  within  the  buffer 
should  be  two  words  grea  er  than  thr  size  of  the  data  portiori  of  the 
message  specified  in  the  directive. 

If  no  data  has  been  sent,  a  task  exit  occurs.  To  pievent  the  possible 
loss  of  send  data  packets,  the  user  should  not  rely  on  I/O  rundown  Lo 
take  care  of  any  outstanding  I/O  or  open  files;  the  task  should 
assume  this  responsibility. 

Buffer  size  can  be  256.  words  maximum.  If  no  buffer  size  is 
specified,  the  buffer  size  is  13.  words.  If  a  buffer  size  greater 
than  256.   is  specified,  an  IE. IBS  error  is  returned. 

Variable-length  data  blocks  are  transferred  from  the  sending  task  to 
the  receiving  task  by  means  of  buffers  in  the  secondary  pool. 

FORTRAN  Call : 

CALL  VRCX  ( [task]  ,bufadr,[buflenH, ids] ) 

task   =   Sender  task  name 

buf    =  Address  of  buffer  to  receive  the  sender  task  name  and 
data 

buflen  =   Length  of  buffer 

ids    =   Integer  to  receive  the  directive  status  word 

If  the  directive  was  successtul,  it  returns  the  number  o.   words 

transferred   Into   the   user   buffer.   If  the  directive  execution 

encountered  an  error,  it  returns  the  error  code  in  the  ids 
parameter. 

Any  error  return  of  the  form  IE. XXX  is  a  negative  word  value.  If 
the  status  is  positive,  the  value  of  the  status  word  is  the 
number  of  words  transferred  including  the  taskname.  For  example, 
if  you  specify  a  buffer  size  of  13  in  the  VRCX$  call,  the  value 
returned  in  the  directive  status  word  is  15  (13  words  of  data 
plus  the  two  words  needed  to  return  the  taskname) . 

Macro  Call: 

VRCX$  [task] ,bufadr[, buflen] 

task        =      Sender    task   name 

bufadr   =      Buffer    address 

buflen   =      Buffer   size    in   words 
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Macro    Expansion! 

VRCX$  SNDTSK,DATBUF,BUFSIZ 

.BYTE  77., 6  ;VRCX$    MACRO    DIC,     DPB    SIZK-6    WORDS 

.RAD50  /SNDTSK/  ; SENDER    TASK    NAME 

.WORD  DATBUP  ; ADDRESS    OF    DATA    BUFFER 

.WORD  BUPSIZ  ;b'JPrER    SIZE 

Local    Symbol  Definitions: 

R.VXTN  —     Sender    task   name    (4) 

R.VXBA  —      Duffer    address    (2) 

R.VXBL  —   Buffer  length  (2) 

R.VXTI  -   Reserved  (2) 
DSW  Return  Codes: 

TS.SUC  —   Successful  completion. 

IB. INS  —   Specified  task  not  Installed. 

lE.RBS  —  Receive  buffer  is  too  small. 

IE. IBS  —   Invalid  buffer  size  specified  (greater  than  255.). 

lE.ADP  —  Part  of  the  DPB  or  buffer  is  out  of  the  Issuing 
task*s  address  space. 

lE.SDP  --  DIC  or  DPB  size  is  invalid. 
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5.3.89  Variable  Sand  Data 

The  Variable  Send  Data  directive  Instructs  the  system  to  queue  a 
variable-length  data  block  for  the  speclCled  task  to  receive. 

Buffer  size  can  be  256.  words  maximum.  If  no  buffer  size  Is 
specified,  the  buffer  size  is  13.  words.  If  a  bufter  size  greater 
than  256.   Is  specified,  an  IE.  IBS  error  is  returned. 

When  an  event  flag  Is  specified,  a  significant  event  Is  declared  if 
the  directive  is  successfully  executed,  and  the  indicated  event  flag 
Is  set  for  the  sending  taak. 

Variable-length  data  blocks  are  transferred  from  the  sending  task  to 
the  receiving  task  by  buffers  In  the  secondary  pool. 

FORTRAN  Call: 

CALL   VSDA    (task, bufadr,  [buflen]  ,  [efnU, ids)  ) 

>  Receiver    task    name 

>  Address  of  buffer  to  receive  the  receiver   task   name 
and  data 

Length  of  ouffer 

■   Event  flag  number 

=   Integer  to  receive  the  directive  status  word 

task, bufadr [, buflen]  [,efnl 

•      Receiver    task   name 

;  bufadr  ■     Buffer   address 

buflen   =      Buffer    size    in   words 

Macro    Expansion: 

VSDA$  RECTSK,DATBUF,BUFSIZ,4 

.BYTE  71., 8  ;VSDA$    MACRO    DIC,     DPB    SIZE=8    WORDS 

.RAD50  /RECTSK/  .-RECEIVER    TASK    NAME 

.WORD  DATBUF  ; A DDR ESS    OF    DATA    BUFFER 

.WORD  4  ; EVENT    FLAG    4 

.WORD  BUFSIZ  ;BUFFER    SIZE 

Local    Symbol    Definitions: 

S.DATN       --      Sender    task   name    (4) 

S.DABA      —      Buffer    address    (2) 

S.DAEF      —      Event    flag    number    (2) 

S.DABL      ~      luffer    length    (2) 

S.DATI      —      Reserved    (2) 
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task 

buf 

buflen 

•£n 

Ids 

Macro  Call: 

VSDA$ 

task 

DIRECTIVE  DESCRIPTIONS 

DSW  Return  Codas i 

IS. sue   —  Successful  completion. 

lE.UPN  —  Insufficient  dynamic  storage. 

IE. INS   —  Specified  task  not  installed. 

IE. IBS   —   Invalid  buffer  size  specified  (greater  than  255.) 

lE.IEF  —  Invalid  event  flag  number  (EFN<0  or  EFN>96) . 

lE.ADP  —  Part  of  the  DFt  or  buffer  is  out  of  the  issuing 
task's  address  space. 

lE.SDP  --  Die  or  DPB  size  is  invalid. 
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5.3.90   Variable  Sand,  Raquast  arid  Connact 

The  Variable  Send,  Request  and  Connect  directive  performs  a  Variable 
Send  Data  to  the  specified  task,  requests  the  task  if  it  is  not 
already  active,  and  then  connects  to  the  task.  The  receiver  task 
normally  returns  status  by  the  Emit  Status  or  the  Exit  With  Sta^'.us 
directive. 

Buffer  size  can  be  256.  words  maximum.  If  no  buffer  ^Ize  is 
specified,  the  buffer  size  is  13.  words.  If  a  buffer  size  greater 
than  256.   Is  specified,  an  IE. IBS  error  Is  returned. 

FORTRAN  Call: 

CALL  VSRC  (rtname,  iouf ,( ibuflen] ,( iefn] ,[  last) , t iesb] ,( iparm)  [,  ids) ) 

rtname   ■   Target   task   name   of   the   offspring   task   to   be 
connected 

ibuf    ■  Name  of  send  buffer 

ibuflen  ■   Length  of  the  buffer 

iefn    ■   Event  flag  to  be  set  when  the  offspring   task   exits 
or  emits  status 

last    ■  Name  of   an   AST   routine   to   be   called   when   the 
offspring  task  exits  or  emits  status 

iesb    ■  Name  of  an  8-word  status  block  to   be   written   when 
the  offspring  task  exits  or  emits  status 

Word     0  —  Offspring  task  exit  status 

Word     1  —  TKTN  abort  code 

Word   2-7  —  Reserved 

NOTE 

The  exit  status  block  defaults  to  one 
word.  To  use  the  8-word  exit  status 
block,  you  must  specify  the  logical  or 
of  the  symbol  SP.WX8  and  the  event  flag 
number  in  the  Iefn  parameter  above. 

iparm   =«  Name  of  a  word  to  receive  the  status  block   address 
when  an  AST  occurs 

ids     =■   Integer  to  receive  the  Directive  Status  Word 
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Macro  Callt 
VSRC$ 
tnam* 

buf 

buf l«n 
«fn 

•  ast 

••b 


t nam*, buf [,bafl«n1 , [•fn] , (•ast] ,»it! 

■  Target   task   name  of   the   offspring   task   to   b* 
connected 

■  Address  of  send  buffer 

■  Longth  of  buffer 

"  The  event  flag  to  be  cleared   on   Issuance   and   set 
when  the  offspring  task  exits  or  umits  status 

■  Address  of  an  AST  routine   to   be   called   when   the 
offsprinc,  task  exits  or  emits  status 

■  Address  of  an  8-word  status  block  to  be  written  when 
the  offspring  task  exits  or  emits  statu;) 

Word    0  —  Offspring  task  exit  status 

Word    1  --  TKTN  abort  code 

Word  2-7  --  Reserved 


Macro  Expansion: 


NOTE 

The  exit  status  block  defaults  to  1  on* 
word.  To  use  the  8-word  exit  status 
block,  you  must  specify  the  logical  or 
-it  the  symbol  SP.WX8  and  the  event  flag 
number    in   the   efn    parameter    above. 


VSRC$ 

ALPHA, B 

.BYTE 

1  4  1 .  ,  9 

.RAD50 

/ALPHA/ 

.WORD 

BUFFR 

.BYTE 

2 

.BYTE 

16. 

.WORD 

aUFSIZE 

.WORD 

SDRCTR 

.WORD 

STBLK 

ALPHA,BUFFR,3UFSIZF.,  2,  SDRCTR,  STB  LK 


;VSRC$    MACRO    DIG,     DPB    SIZE-8    WORDS 
;TAHGET   TASK   NAME 
;SEND   BUFFER    ADDRESS 
;EVEMT    fLAG    NUMHER    «    2 
;EXIT    STATUS    BLOCK   CONSTANT 
.•LENGTH    OF    BUFFER    IN    BYTES  , 

;ADDRESS    OF    AST    ROUTINE 
;ADDRESS    OF    STATUS    BLOCK 


Local    Symbol  Definitions: 

S.DRTN  —     Task   name    (4) 

S.DRBF  --      Buffer    address    (2) 

S.DREF  --      Even':    fl         '.2) 

S.DREA  —   AST  routi,.e  address  (2) 

S.DRES  —   Status  block  address  (2) 


/ 


/ 
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DSW  Return  Codes t 

IS. sue   —  Successful  completion. 

lE.UPN  —  Insufficient  dynamic  memory  to  allocate  a  send 
packet,  Offspring  Control  Dlock,  Task  Control  BlocK, 
or  Partition  Control  Block. 

IB. INS  —  The  specified  task  is  an  ACP  or  has  the  no-send 
attribute. 

lE.IEF  —  An  invalid  event  flag  number  was  specified  {EFN<0  or 
EFN>96  if  group  global  event  flags  exist.  EFN>64  if 
not.)  . 

lE.ADP  —  Part  of  the  DPS  or  exit  status  block  is  not  in  the 
issuing  task's  address  space. 

IF.SDP  —  Die  or  DPP  size  Is  invalid. 

Notes: 

1.  If  the  specified  event  tlag  is  group  global,  the  use  count 
fo.  the  event  flag's  group  is  Incremented  to  prevent 
premature  elimination  of  the  event  flags.  The  use  count  is 
run  dovm  when: 

•  Status  is  returned  from  the  < onnected  task. 

•  The  issuing  task  exits  before  status  is  returned. 

2.  Changing  the  virtuaJ  mapping  of  the  exit  status  block  while 
the  connection  is  in  effect  may  result  in  obscure  errors. 
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WSIG$S 


5.3.91   Walt  For  Significant  Event  ($S  Por«  Recoamet'ded) 

The  Walt  For  Significant  Event  directive  Is  used  to  suspend  the 
execution  of  the  issuing  task  until  the  next  significant  event  occurs. 
It  Is  an  especially  effective  way  to  block  a  task  that  cannot  continue 
bee  luse  of  a  lack  of  dynamic  memory,  since  significant  events 
occurring  throughout  the  system  often  result  in  the  release  of  dynamic 
memory.  The  execution  of  i  Wait  For  Significant  Rvent  directive  Joes 
not  itself  constitute  a  significant  event. 

FORTHAN  Call : 

CALL  WFSNE 
Macro  Cal 1  : 

WSIG$S   [err] 

err   =  Error  routine  address 
Macro  Expanslont 


WSIG$S  ERR 

MOV  (PC)+,-(SP) 

•  BYTJ:  49.,  1 

EMT  377 

BCC  .+6 

JSR  PC, ERR 


PUSH  D?B  ONTO  THE  STACK 

WSIGSS  MACRO  ::5IC,  DPB  S1ZE  =  1  WORD 

TRAP  TO  THE  EXECUTI JE 

BRANCH  IF  DIRECTIVE  SUCCESSFUL 

OTHERWISE,  CALL  ROUTINE  "ERR" 


Local  Symbol  Definitions: 

None 
DSW  Return  Codes: 

IS. sue   —   Successful  completion. 

lE.ADP      - 


lE.SDP 


Part   of    the    DPB    is   out   of    the    issuing    task's      address 
".pare. 

Die   or    DPB   size    is    i.Tvalid. 


Notes : 
1, 


If  a  directive  is  rejected  for  lack  of  dynamic  memory,  thir 
dire^'tlve  is  the  only  technique  available  for  blocking  task 
execution  until  dynamic  memory  may  again  be  available. 

The  wait  state  induced  by  this  directive  is  satisfied  by  the 
first  significant  event  to  occur  after  the  directive  has  been 
issiic>d.  The  significant  event  that  occurs  may  or  may  not  be 
related  to  the  issuing  task. 

Because  this  directive  requires  only  a  1-word  DPB,  the  $S 
form  of  the  macro  is  recommended.  It  requires  less  space  and 
executes  with  the  same  speed  as  that  of  the  DIRS  macro. 
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4.   Significant  events  Include  the  following: 

I/O  completion 

Ta  3  k  exit 

Execution   of   a    Send    Data   directive 

Execution   of    a    Send    Data,    Request    and    Pass    (X;B  directive 

Execution   of   a    Send,    Request    and    Connect   directive 

Execution  of  a  Send  By  Reference  directive  or  a  R«>ceive  by 
Reference   directive 

Execution   of    an    Alter    Priority  directive 

Removal  of  an  entry  from  the  clock  qu>  ue  (for  Instance, 
resulting  fro  i  the  execution  of  a  Mark  Time  directive  or 
the    Issuance   of    a    rescheduling    request) 

Execution    of    a    Declare    Significant    Event   directive 

Execution  of  the  round-robin  scheduling  algorit-hm  rat  the 
end    of    a    round-robin    scheduling    interval 

Execution  of  an  Exit,  an  Exit  with  Status,  or  Emit  Status 
d I rect Ive 
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WTLO$ 

5.3.92      Walt    For    lo^   cal    OR   Of    Event    Flags 

The  Walt  For  Logical  CR  Ot  Event  Flags  directive  Instructs  the  system 
fh-  V^?  /^®  execution  of  the  Issuing  task  until  the  Executive  sets 
tne    indicated   event    flags    from   one   of    the    following   groups: 

GR  0  --  Flags  1-16 

GR  1  —  Flags  17-32 

GR  2  --  Flags  33-49 

GR  3  --  Flagb  19-64 

GR  4  --  Flags  65-80 

GR  5  --  Flags  81-96 

The  task  does  not  block  Itself  If  any  of  the  lndi<.-ated  flags  are 
already   set    when    the    task    Issues    the   directive.      See    Notes   below. 

FORTRAN   Call : 

CALL   WFLOR     (ef n  1 , e f n2 , . . .e f nn) 

efn   =   List  of  event  flag  numbers  taken  .is  the  set  of  flags  to 
be  specified  in  thp  directive 

Macro  Ca 11  : 

WTLO$        grp,msk 

grp      =      Desired    group   of    event    flags 

msk      =      A    16-bit    flag    mask    word 
Macro    Expansion: 

WTLO$         2,160003 

'?^rll         ?^*'-^  ;WTLO$    MACRO    DIC,    DPB    SIZE  =  3    WORDS 

•WORD         2  ; FLAGS    SET    NUMBER    2     (FLAGS    3  3:48.) 

.WORD         160003  ;EVENT    FLAGS    33,34,46,47    AND    48. 

Local    Symbol    Definitions: 

None 
DSW    Return    Codes: 

IS. sue      —      Successful    completion. 

lE.IEF      —      No    event    flag    specified    In      the      mask      word      or       flag 
group    indicatoi    other    than    0,    1,    2,    3,    4,    or    5. 

lE.ADP      --      Part    of    the    DF3    is    out    of    the    Issuing    task's      address 
space. 

lE.SDP      —      DIC   or    DPB   size    is    invalid. 
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Notes ; 


1.  There  is  a  one-to-one  correspond«|ie*  bttween  bits  in  the  mask 
word  and  the  event  flags  In  the  dpeeifled  grj.ip.  That  Is,  if 
group  1  were  specified,  then  bit  0  in  the  mask  word  would 
correspond  to  event  flag  17,  bit  1  to  event  flag  18,  and  so 
forth. 

2.  The  Executive  does  not  arbitrarily  clear  event  flags  when 
Wait  For  conditions  are  met.  Some  directives  (Queue  I/O 
Request,  for  example)  Implicitly  clear  a  flag;  otherwise, 
they  must  be  explicitly  cleared  by  a  Clear  Event  Flag 
d I rect Ive  . 

3.  The  grp  operand  must  always  be  of  the  form  n  regardless  of 
the  macro  form  used.  In  all  other  macro  calls,  numeric  or 
address    values    for    SS    form    macros    have    the    form: 

*n 

For  WTLO$S  this  form  of  the  grp  argument  would  be: 


The  argument  list  specified  In  the  FORTRAN  call  must  contain 
only  event  flag  numbers  that  lie  within  one  event  flag  group. 
If  event  flag  numbers  are  specified  that  lie  In  more  than  one 
group,  or  if  an  Invalid  event  flag  number  is  specified,  a 
fatal  FORTRAN  error  Is  generated. 

If  the  Issuing  task  has  outstanding  buffered  I/O  when  It 
enters  the  Wait  For  state,  it  will  be  stopped.  When  the  task 
is  in  a  stopped  state,  it  can  be  checkpolnted  by  any  other 
task  regardless  of  priority.   The  task  is  unstopped  when: 

•  The  outstanding  buffered  I/O  completes. 

•  The  Walt  Cor  condition  Is  satisfied. 

If  the  specified  group  of  event  flags  Is  group  global,  the 
group's  use  count  is  Incremented  to  prevent  premature 
elimination  of  the  event  flags.  The  use  count  is  run  down 
when : 

•  The  Walt  For  condition  is  satisfied. 

•  The  Issuim  task  exits  before  the  Wait   For   condition   Is 
sat isf  led  . 
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5.3.93   Wdit  For  Slnqle  Event  Flag 

The  Walt  For  Slnqle  Event  Flaq  directive  Instructs  the  sy.st»>m  to  block 
the  execution  of  the  lasulnq  task  until  the  Indicated  event  flaq  l3 
set.   If  the  flaq  Is  set  at  Issuance,  task  execution  Is  not  blocked. 

FORTRAN  Cal l : 

CALL  WAITFR  (efn[ ,lds| ) 

efn   =»   Event  flaq  number 

ids   =   Directive  status 

Macro  Cal 1  : 

WTSE$    efn 

efn   =   Event  flaq  number 

Macro  Expansion: 

WTSE$    52. 

.BYTE         41., 2  ;WTSE3    MACRO    DIG,    DPB    SIZE-2    WORDS 

•  WORD         52.  ;EVENT    FLAG    NUMBER    ,'-.2. 

Local    Symbol    Definitions; 

W.TSEF      --      Event    flaq    number    (2) 
DSW   Return    Codes: 

IS. sue      --      Successful    completion. 

lE.IEF  --  Invalid  event  flaq  number  (EFN<1,  or  EFN>96  If  group 
global  event  flags  exist  for  the  task's  group;  or 
EFN>64    if    not) . 

lE.ADP  --  Part  of  the  DPB  is  out  of  the  issuing  task's  address 
space . 

lE.SDP      --      Die   or    DPB   size    Is    invalid. 

Notes : 

1.  If  the  issuing  task  has  outstandinq  buffered  I/O  whpn  it 
enters  the  Wait  For  state.  It  will  be  stopped.  When  the  task 
is  in  a  stopped  state,  it  can  be  checkpointed  by  any  other 
task  reqardless  of  priority.   The  task  is  unstopped  when: 

•  The  outstanding  buffered  I/O  completes. 

•  The  Wait  For  condition  is  satisfied. 

2.  If  the  specified  event  flaq  is  qroup  global,  the  group's  use 
count  is  incremented  to  prevent  premature  elimination  of 
event  flags.   The  use  count  is  run  down  when: 

•  The  Wait  For  condition  is  satisfied. 

•  The  issuing  task  exits  before  the  Wait   For   condition   is 
sat i  sf led . 
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DIRECTIVE  SUMMARY  -  ALPHABETICAL  ORDER  BY  MACRO  CALL 

Abort  Task  AHRT$ 

FORTRAN  Call : 

CALL  ABORT  (tsk( , Ids) ) 

tsk   »   Task  name  to  be  aborted  {RAD50) 
ids   »   Directive  statas 
Macro  Cal 1 : 

ABRT$    tsk 

tsk   =«   Task  name  to  be  aborted  (RAD50) 

Alter  Priority  ALTP$ 

FORTRAN  Call  : 

CALL   ALTPRI     (  [  l  sk  ]  ,  [  1  pr  I )  (  ,  I  ds  1  ) 

tsk      =      Active    task    name 

iprl    =      A    1-word    inteqer    value    equal    to    the    now   priority,      from 
1    to    250    (decimal) 

ids  =      Directive    status 

Macro   Ca  1 1  : 

ALTPS         [tski  f ,pri J 

tsk  =      Active    task    name 

pri  =      New   priority,    from    1    to    250    (decimal) 
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Assign  LUN  ^^^^^ 

FORTRAN  Call : 

CALL  ASN.,UN  ( 1  un  ,dev  ,un  c  [  ,  ids]  ) 

lun   =   Logical  unit  number 

dev   =   Device  name  (format:   1A2) 

unt   =   Device  unit  number 

ids   =   Directive  status 
Macro  Cal 1 : 

^LUNS    lun, dev, unt 

lun   =   Logical  unit  number 

dev   =   Device  name  (two  characters) 

unt   =   device  unit  number 

AST  Service  Exit  ($S  form  recommerded)  A5;tx$S 

fURiHAK  Cal  '.  : 

Neithor  the  FORTRAN  language  nor  the  ISA  standard  permits  direv-L 
lini-ing  to  system-trapping  r-echanisms;  therefore,  this  directive 
is    not    available    to    FORTRAN    tasks. 

Macro   Cal 1  : 

ASTX$S       [err] 

err      =      Error    routine    -.ddress 

Attach    Region  ATRGS 

FORTRAN   Call  : 

CALL   ATRG     (irdbj ,ids] ) 

irdb   =      An    8-word    intege--    array   containing    a    Region      Defiriition 
Block    (see    Section    3.5.1.2) 

ids  =      Directive    status 
Macro    Cf-'ll  : 

ATRGS  rdb 

rdb  =   Region  Definition  Block  au-'ress 

Connect  To  Interrupt  Vector  CINT$ 

FORTRAN  Ca  11 : 

Not  supported 
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Macro  Call : 

CINT$   vec ,base,Isr ,edir ,pr I ,ast 

vec  =  Interrupt  vector  address  —  Must  be  in  the  range  60(8) 
to  highest  vector  specified  during  SYSGEN,  inclusive, 
and  must  be  a  multiple  of  4 

base  =  Virtual  base  address  for  kernel  APR  5  mapping  of  the 
ISR,  and  enable/disable  interrupt  routines 

isr  =  Virtual  address  of  the  ISR,  or  0  to  disconnect  from  the 
interrupt  vector 

edir  =  Virtual  address  of  the  enable/disable  Interrupt  routine 

pr  i   =   Initial  priority  at  which  the  ISR  is  to  execute 

ast  =  Virtual  address  of  an  AST  routine  to  be  entered  after 
the  fork-level  routine  queues  an  AST 

Clear  Event  Flag  CLEF$ 

FORTRAN  Call : 

CALL  CLREF  (efn[,ids] ) 

efn   =   Event  flag  number 
ids   =   Directive  status 
Macri  Call : 

CLEFS   efn 

efn   =   Event  fi=»q  number 

Cancel  Mark  Time  Requests  CMKT$ 

FORTRAN  Ca^l : 

CALL  CANMT  ([efn]  [,ids]  ) 

efn   =   Event  flag  number 

ids   =   Directive  status 
Macro  Call : 

CMKT$   [efn, ast , err] 

efn   =   Event  flag  number 

ast   =   Mark  time  AST  address 

err   =   Error  routine  address 
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Connect  CNCT$ 

FORTRAN  Call : 

CALL  CNCT  (rtname,[lefn] , [ last] , ( iesb] , [ iparm]  [,Ids]  ) 

rtname   =   Name  (RAD50)  of  the  offspring  task  to  *•      connecced 

iefn    =   Event  flag  to  be  set  when  the  offspring   task   exits 
or  emits  status 

last    =   Name  of   an   AST   routine   to   be   called   when   the 
offspring  task  exits  or  emits  status 

iesb    =   Name  of  an  8-word  status  block  to   be   written   when 
the  offspring  task  exits  or  emits  status 

Word    0  --  Offspring  task  exit  status 

Word  1-7  —  Reserved 

iparm   =   Name  of  a  word  to  receive  the  status   block   address 
when  an  AST  occurs 

Ids  =   Integer  to  receive  the  Directive  Status  Word 

Macro  Call : 

CNCT$  tname,  [efn] , [east ] , [esb] 

tname  =   Name  (RAD50)  of  the  offspring  task  to  be  connected 

efn     =   The  event  flag  to  be  cleared   on   issuance   and   set 
when  the  offspring  t^sk  exits  or  emits  status 

east    =   Address  of  an  AST  routine   to   be   called   when   the 
offspring  task  exits  or  emits  status 

esb     =   Address  of  an  8-word  status  block  to  be  written  when 
the  offspring  task  exits  or  emits  status 

Word    0  --  Offspring  task  exit  status 

Word  1-7  --  Reserved 

Checkpoint  Common  Region  CPCR$ 

FORTRAN  Call : 

CALL  CPCR    (name(,ids) ) 

name  =  Name   {in   RAD50)   of   the   common   region   to   be 
checkpointed 

ids   =  Directive  status 
Macro  Call : 

CPCR$  name 

name  =  Name  of  the  common  region  to  be  checkpointed 
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Create  Address  Window  CRAM$ 

FORTRAN  Call : 

CALL  CRAW  f iwdb[ ,lds] ) 

Iwdb  =   An  8-word  Integer  array  containinq  a  Window   btjfinition 
Block  (see  Section  3.5.2.2) 

Ids   =   Directive  status 

Mc  cro  Call : 

CRAW$    wdb 

wdb   =   Window  Definition  Block  address 

Create  Group  Global  Event  Flags  CRGF$ 

FORTRAN  Call : 

CALL  CRGF  { [group]  [,  ids] ) 

group  =  Group  number  for  the  flags  to  be  created  -  If  not 
specified,  the  task's  protection  UIC  (H.CUIC+1)  in 
the  task's  header  Is  used 

ld8     -■   Integer  to  receive  the  Directive  Status  Word 

Macro  Call : 

CRGF$  [group] 

group  =  Group  number  for  the  flags  to  be  created  -  If  not 
specified,  the  task's  protection  UIC  (H.CUIC+1)  in 
the    task's   header    is    used 

Create    Region  CRRG$ 

FORTRAN   Call : 

CALL   CRRG    (irdb[  ,i.1s]  ) 

Irdb   =      An    8-word    integer    array  containing    a    Region      Definition 
Block    (see    Seccion    3.5.1.2) 

ids  =      Directive    status 

Macro   Cal 1 : 

CRRG$         Ldb 

rdb  =      Region    Definition    Block    address 
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Create  Virtual  Terminal  CRVT$ 

FORTRAN  Call : 

CALL  CRVT  ([liast] , [ioast] , [ laast] , [Imlen] ,iparmt ,ids] ) 

Hast  ■  AST  address  at  which  input  requests  from  offspring 
tasks  are  servlt:ed 

ioast  »  AST  address  at  which  output  requests  from  offspring 
tasks  are  serviced 

laast  *  AST  address  at  which  the  parent  task  may  be  notified 
of  the  completion  of  successful  offspring  attach  and 
detach  requests  to  the  virtual  terminal  unit 

imlen  ■  Maximum  buffer  length  allowed  for  offspring  I/O 
requests 

Iparm  "  Address  of  3-word  buffer  to  receive  information  from 
the  stack  when  an  AST  occurs 

Ids     «   Integer  to  receive  the  Dire'ctlve  Status  Word 

Macro  Call: 

CRVT$    [last] , (oast]  ,  [aast] , [mien] 

last  "  ASr  address  at  which  input  requests  from  offspring 
tasks  are  serviced 

t    =   AST  address  at  which  oi'-put  requests  from  offspring 
tasks  are  serviced 

aast  =  AST  address  at  which  the  parent  task  may  be  notified 
of  the  completion  of  successful  offspring  attach  and 
detach  requests  to  the  virtual  terminal  unit  (If 
this  parameter  is  not  specified,  no  notification  of 
attaches  and  detaches  are  returned  to  the  parent 
task . ) 

mien  =  Maximum  buffer  length  allowed  for  offspring  I/O 
requests 

Cancel  Time  Based  Initiation  Requests  CSRO$ 

FORTRAN  Call : 

CALL  CANALL  ftskf  ,ids]  ) 
tsk   =   Task  name 
ids   =   Directive  suatas 
Macro  Call  : 

CSRQS   tsk 

tsk   =   Task  nan  e 
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Declare  Signiiicant  Event  ($S  form  recoamended)  DECLSS 

FORTRAN  Call : 

CALL  DECLAR  (  [  ,lds]  / 

Ids   =   Directive  status 
Macro  Cai 1 : 

DECL$S   [,err) 

err   =  Error  routine  address 

Disable  AST  Recognition  ($S  form  recommended)  DiiAR$S 

FORTRAN  Call : 

CALL  DSASTR  [  (ids) ] 

ids   =   Directive  status 
Macro  Cal 1 : 

DSAR$S   [err] 

err   =   Error  routine  address 

Disable  Checkpointing  ($S  form  recommended)  DSCP$S 

FORTRAN  Call : 

CALL  DISCKP  [  (ids) ] 
ids   =■   Directive  status 
Macro  Call , 

DSCP$S   [err] 

err   =   Error  routine  address 

Decach  Region  DTRG$ 

FORTRAN  Call : 

CALL  DTRG  (irdb[ ,ids] ) 

irdb  =   An  8-word  integer  array  containing  a  Region   Definition 
Block  (see  Section  3. 5.1.2) 

ids  =   Directive  status 

Macro  Call: 

DTRGS    rdb 

rdb  -   Region  Definition  Block  address 


A-7 


DIRECTIVE    SUMMARY    -    ALPHABETICAL   ORDER   BY   MACRO  CALL 


Eliminate   Address  Window 

r^ORTRAH   Call  ! 

CALL   ELAW    (iwdb[  ,ldsl ) 

iwdbl        =     An      8-/ord      integer      array        containing 
Definition    Block    (see    Section    3.5.2.2) 


ids 
Macro   Cal ',  ; 
ELAW$ 
wdb 


Directive    status 


wdb 


Window  Definition  Block  address 


ELAH$ 


Wi  ndow 


Eliminate   Group  Global    Event    Flags 
FORTRAN   Call  : 

CALL    ELGF    ( [group] [,ldsl ) 

group      =      Group   number    of    flags    to    be    eliminated 
ids  =      Integer    to    receive    the    Directive    Status   Word 

Macro   Cal 1 ; 

ELGFS  [group] 

group      =      Group  number    of    flags    to    be   eliminated 


KLCP$ 


Eliminate   Virtual   Teralnal  KLVTt 

FORTRAN   Call  : 

CALL   ELVl"    (iunuin[,lds]  ) 

lunum        =  rtual    terminal    unit   number 

ids  -      Integer    to    receive   th**   Directive   Status  Word 

Macro  Call : 

ELVT$        unum 

unum    -   Unit  number  of  the  virtual  terminal  to  be  eliminated 


Emit  Status  EH5T$ 

FORTRAN  Call : 

CALL  EMST  ( [  rtname] , i sta t [ , i d s] ) 

rtnane   =   Name  of  task  connected  to  issuii^g  task  to  which   the 
status  is  to  be  emitted 


istat 


ids 


A  i6-bit  quantity  to  be  returned   to   the   connected 
task 

Integer  to  receive  the  Directive  Status  Word 
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Macro  Call : 

EMST$    [tnaitie]  , status 

tname    =   Name  of  a  task  connected   to   the   issuing   task   to 
which  the  status  is  to  be  emitted 

status   =   A  16-bit  quantity  to  be  returned   to   the   connected 
task 


Enable  AST  Recognition  {$S  form  recommended) 

FORTRAN  Call : 

CALL  ENASTR  [  (idr) ] 

ids   =   Directive  status 
Macro  Cal 1 : 

ENAR$S   [err] 

err   -   Error  routine  address 


ENAR$S 


Enable  Checkpointing  ($S  form  recommended) 

FORTRAN  Call : 

CALL  ENACKP  [  (ids) ] 

ids   =   Directive  status 
Macr-.->  Call  : 

F.NCPSS   [err] 

err   =   Error  routine  address 


ENCP$S 


E-  <  c  If 
FORTRAN  Call : 

CALL  EXITIF  (efn[ ,ids] ) 
efn   =   Event  flag  number 
ids   =   Directive  status 
Macro  Cal 1 : 

EXIFS   efn 

efn   =   Event  flag  number 


Exip; 
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Task  Exit  ($S  form  recommended)  EXIT$t' 

FORTRAN  Call  : 

Fortran  tasks  that  terminate  with  the  STOP  stattrent  result  in  a 
message  that  includes  task  name,  a  statement  causing  the  task  ,o 
stop,  and  an  optional  character  string  specified  in  the  STOP 
statement.  CALL  EXIT  terminates  with  the  message  STOP  THIS 
FORTRAN  TASK. 

Macro  Call : 

EXIT$S   [err] 

err   =   Error  routine  address 

Exit  With  Status  EXST$ 

FORTRAN  Call  : 

CALL  EXST  (istat) 

istat    =   A  16-bit  quantity  to  be  returned  to  parent  task 
Macro  Call : 

EXST$    status 

Status   =   A  16-bit  quantity  to  be  returned  to  parent  task 

Extend  Task  EXTK$ 

FORTRAN  Call : 

CALL  EXTTSK  ([inc]  [,idsl ) 

inc  =  A  positive  or  negative  number  equal  to  the  number  of 
32-word  blocks  by  which  the  task  size  is  to  be  extended 
or  reduced  (If  omitted,  task  size  defaults  to  installed 
task  size.) 

Ids   =   Directive  status 

Macro  Cal 1 : 

EXTK$    [inc] 

ir.c  =  A  positive  or  negative  number  equal  to  the  number  of 
32-word  blocks  hy  which  the  task  is  to  be  extended  or 
reduced  (If  omitted,  task  sizo  defaults  to  installed 
task  si  ze  . ) 

Get  Command  for  Command  Interpreter  GCCI$ 

Fortran  Call : 

CALL  GTCMCI  ( icbf , icbf 1 , [ i i buf ] , [ i i bf 1 ] , [ iaddr ] , [ incp]  [ , ids] ) 
icbf   =  Name  of  a  byte  to  receive  the  command 
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icbfl  =  Integer  containing  the  size  of  the  icbf  array  in  bytes 

iibuf  =  Name  of  an  integer  containing  the  length  of  the 
optional  information  buffer 

iaddr  -  Name  of  an  integer  that  contains  the  address  in  pool  of 
the  comitfand  desired  (This  address  was  obtained  by  a 
previous  call  to  GTCMCI  with  GC.CND  specified.) 

Incp  =  Name  of  an  integer  containing  a  value  Indicating  the 
action  to  take  if  there  is  no  command  queued 

ids    =  Integer  to  receive  the  directive  status  word 

Macro  Cal 1  : 

GCCI$  cbuf ,cbfl  .  [ibuf ] , [Ibfl] , [addr] , [ncp] 

cbuf   =  Address  of  buffar  to  receive  command  string 

cbfl  =  Length  of  buffer.  Maximum  buffer  size  Is  84.  for 
RSX-llM  and  259.   for  RSX-llM-PLUS. 

ibuf  =  Address  of  buffer  to  receive  information  on  the  issuing 
terminal 

ibfl   =  Length  of  buffer  to  receive  information 

addr   =  Address  of  command 

ncp   =  Action  to  take  if  no  command  buffer  is  present 

GC.CCS  (000)  —  Return  with  carry  set  (default) 

GC.CEX  (001)  —  Force   CLI   to    exit    instead    of 
returning 

GC.CST  (002)  --  Force   CLI   to    stop    instead    of 
returning 

GC.CND  (200)  --  Copy  command  into  buffer  but  do   not 
dequeue  it  from  the  list 

Get  Command  Interpreter  Information  GCII$ 

FORTRAN  Call : 

CALL  GETCII  ( i  buf  ,  i  b  f  1 ,  Mel  i  ]  ,  [  idev  ]  ,  [  iun  i  t  ]  (  ,  ids] 

ibuf   =  Name  of  an  integer  array  to  receive  the  CLE  information 

ibfl  =  Length  in  bytes  of  the  integer  array  to  receive  the  CLI 
information 

icli  =  Name  of  a  2-word  c-rray  element  containing  the  RAD50 
name  of  the  CLI 

idev  =  Name  of  an  integer  containing  the  ASCII  name  of 
terminal  (default  =  TI:) 

iunit  =  Name  of  an  integer  containing  the  octal  unit  number  of 
terminal 

ids    =  Directive  status 
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Macro  Cal 1 : 

GCII$  buf ,bufl  ,cli, [dev] , [unit] 

buf    =  Address  of  buffer  to  receive  information 

bufl   =  Length  of  information  buffer 

cli    =  Name  in  RAD50  of  the  CLI  that  information  is   requested 
on 

dev    =»  ASCII  name  of  terminal  whose  CLI  should  be  used 

unit   =  Octal  unit  number  of  terminal 

Get  LUN  Information  GLUN$ 

FORTRAN  Call : 

CALL  GETLUN  (1 un ,da t ( , ids] ) 

lun   =   Logical  unit  number 

dat   =  A  6-word  integer  array  to  receive  LUN  information 

ids   =   Directive  status 

Macro  Call  : 

GLUN$   lun, buf 

lun   =   Logical  ur i t  number 

buf   =  Address  of  6-word  buffer   that   will   receive   the   LUN 
information 

Get  MCR  Command  Line  GMCR$ 

FORTRAN  Call  : 

CALL  GETMCR  (buf [, ids] ) 

buf   =  An  80-byte  array  to  receive  command  line 
ids   =   Directive  status 
Macro  Cal 1  : 
GMCRS 
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Get  Mapping  Context  GIICX$ 

FORTRAN  Call : 

CALL  GMCX  (imcx[,ids] ) 

imcx  =  An  integer  array  to  receive  the  mapping  context.  The 
size  of  the  array  is  8*n+l,  where  n  is  the  number  of 
window  blocks  in  the  task's  header  (The  maximum  size  is 
8*8  +  1-65  on  RSX-llM  systems.  The  i.iaximum  size  is 
8*24+1-193  on  RSX-llM-PLUS  systems.) 

ids   =   Directive  status 

Macro  Cal 1  : 

GMCX$    wvec 

wvec  =  The  address  of  a  vector  of  n  Window  Definition  Blocks; 
n  is  tne  number  of  window  blocks  in  the  task's  header. 

Get  Partition  Parameters  GPRT$ 

FORTRAN  Call : 

CALL  ]ETPAR  ( [ pr t ] , buf [ , ids] 1 

prt   =   Partition  name 

buf   =   A  3-word  integer  array  to  receive  partition  parameters 

ids   =   Directive  status 
Macro  Cal 1  : 

GI.^T$   [prt], buf 

prt      =      Partition    name 

buf      =     Address  of    3-word   buffer 

Get    Rt-yion    Parameters  GREG$ 

FORTRAN   Call : 

CALL   GETREG    (  [  r id ]  , buf [  ,  ids] ) 
rid      =      Region    id 

buf      =      A    3-word    integer    array    to    receive    region    parameters 
ids      =      Directive    status 
Macro   Call  : 

GREGS         [rid], buf 
rid      =      Region    ID 
buf      =      Address   of    3-word    buffer 


A-13 


DIRECTIVE  SUMMARY  -  ALPUABETICAL  ORDER  BY  MACRO  CALL 

Get  Sense  Switches  ($S  form  recommended)  GSSI*$S 

FORTRAN  Call : 

CAt.L  READSW  (  isw) 

isw   =   Integer  to  receive  the  console  switch  settings 

The  following  FORTRAN  call  allows  a    program  to  read   the   state   of   a 
single  switch: 

CALL  SWITCH  (ibt,ist) 

Ibt   =   The  switch  to  be  tested  (0  to  15) 

ist   =   Test  results  where: 

1   =   fvwitch  on 

7      =   swf  tch  off 

Macro  Call  : 

GSSWSS   [err]  p 

err   =   Error  routine  address 

Get  Time  Paramecers  GTIH$ 

FORTRAN  Call : 

CALL  GETTIM  ( iofl [ ,ids! ) 

ibfl   =  *.-!  8-word  integer  array 
ids    =  Directive  status 
Macro  Call : 

GTIM$    buf 

buf   =   Address  of  8-word  buffer 

Get  Task  Parameters  GTSK$ 

FORTRAN  Call  : 

CALL  GETTSK  (buf [ ,idsl ) 

buf   =   A  16-word  integer  array  to  receive  the  task  parameters 
ids   =   Directive  status 
Macro  Cal 1  : 

GTSKS    buf 

buf      =      Address   of    16-word    buffer 


A-14 


DIRgCTIVE  SUMMARY  -  Af.PHABETICAL  ORDKR  BY  MACRO  CALL 

Inhibit  AST  Recognition  ($S  forn  recoamended)  IHARSS 

FORTRAN  Call : 

CALL  INASTR   I  (Ids) ] 

ids      =      Directive    status 
Macro   Ca 11  : 

IhARSS       [err] 

orr      =      Err^r    routint    address 

Map   Address   Window  MAI'$ 

FORTRAN   Call : 

CALL   MAP    (iwdb[  ,idsl ) 

iwdb    =      An    8-word    integer    array   containing    a    Window      Definition 
Block    (see    Section    3.5.2.2) 

ir's   =   Directive  status 

Macro  Cal 1  : 

MAPS    wdb 

wdb   =   Window  Definition  BlocK  addte^3 

Mark  Time  MRKT$ 

FORTRAN  Call  : 

CALL  MARK  (ef n  ,  tmg  ,  tnt  [  ,  ids] ) 

efn   =  Event  flag  number 

tmg   =  Time  interval  magnitude 

tnt   =  Time  interval  un't 

ids   =  Directive  status 

The  ISA  standard  call   for   delaying   a   task   for   a   specified   time 
interval  is  also  Included: 

CALL  WAIT  (tmg, tnt, Ids) 

tmg   =  Time  interval  magnitude 

tnt   =  Time  interval  unit 

ids   =  Directive  status 
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Macro  Call : 

MRKT$    [efn] ,tng,rnt( ,astl 
efn   =   Event  flag  number 
tmg   =   Time  interval  magnitude 
tnt   =   Time  interval  unit 
ast   =   AST  entry  point  address 

Map  Supervisor  D-Space  to  Supervisor  I-Space  MSDS$ 

FORTRAN  Call: 

Not  supported. 
Macro  Call: 

MSDS$    mask 

mask  =  A  7-bit  mask  with  one  bit  corresponding  to  each  APR, 
If  the  bit  is  set,  the  APR  is  mapped  to  supervisor-mode 
I-space.  If  the  bit  is  clear  the  APR  is  mapped  to 
user-mode  D-space.  The  7  bits  are  specified  in  bits  8 
through  14  of  the  mask  word. 

Move  to/from  yse-/Suparvisor  I/D-Space  MVTS$ 

FORTRAN  Call : 

Not  supported. 

Macro  Call: 

MVTS$    action, addr,val 

buff 

action  =  0\e  of  the  following: 

MV.TUI  —  Move  to  user  I-space 

MV.TUD  —  Move  to  user  D-space 

MV.TSI  --  Move  to  supervisor  I-space 

MV.TSD  —  Move  to  supervisor  D-space 

MV.FUI  —  Move  from  user  I-space 

MV.FUD  —  Move  from  user  D-space 

MV.FSI  --  Move  from  supervisor  I-space 

MV. FSD  —  Move  from  supervisor  D-space 

addr    =  Address  of  the  location  in  the  task 

buf     =   Puffer  to  receive  the  value  fetched,   for   the   move 
from  operations 

val     =  Value  to  be  stored  in  the  location,  for  the  move   to 
operations 
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Queue  I/O  Req<^est  QIO$ 

FORTRAN  Call  : 

CALL  QIC  (fnc,lun, [efn] , [prl] , (isb] , tprl] (,ids] ) 

fuc   =   I/O  function  code 

lun   =   Logical  unit  number 

efn   =  Event  flag  number 

pri   =   Priority;   ignored,  but  must  be  present 

isb   =  A  2-word  integer  array  to  receive  final  I/O  status 

prl  =  A  6-word  integer  array  containing  device-dependent 
parameters  to  be  placed  in  parameter  words  1  through  6 
of  the  Directive  Parameter  Block  (DPB) .  Fill  in  this 
array  by  using  the  GETADR  routine  (see  Section 
1.5.  1.4)  . 

ids  =  Directive  status 

Macro  Cal 1 : 

QIO$  fnc,lun, [efn] , [pr i ] , ( isb] , [ast] , [ prl] 

fnc  =  I/O  function  code 

lun  =  Logical  unit  number 

efn  =  Event  flag  number 

pri  =  Priority;   ignored,  but  must  be  present 

isb  =  Address  of  I/O  status  block 

ast  =  Address  of  AST  service  routine  entry  point 

prl  =  Parameter  list  of  the  form  <pl,...p6> 

Queue  I/O  Request  And  Wait  0IOH$ 

FORTRAN  Call : 

CALL  WTQIO  (fnc, lun, [efn] , [?r 1] , [ isb] , [ prl ]  [ ,  ids] ) 

fnc   =   I/O  function  code 

lun   =   Logical  unit  number 

efn      =      Event    flag    number 

pri      =      Priority;      ignored,    but   must    be    present 

isb      =      A    2-word    integer    irray   to    receive    final    I/O   status 

prl  =  A  6-word  integer  array  containing  device  dependent 
parameters  to  be  placed  in  parameter  words  I  through  6 
of    the    DPB 

ids   =  Directive  status 
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Macro  Call : 

0IOW$  fnclun,  [efn]  ,  [pri]  ,  [isb]  ,  [asf]  [,prl] 

fnc  =  I/O  function  code 

lun  =  Logical  unit  number 

efn  =  Event  flag  number 

pri  =  Priority;   ignored,  but  must  be  present 

isb  =  Address  of  I/O  status  block 

ast  =  Address  of  AST  service  routine  entry  point 

prl  =  Parameter  list  of  the  form  <pl,...p6> 

Receive  Data  Or  Stop  HCST$ 

FORTRAN  Call : 

CALL  RCST  ( [rtname] ,ibuf [  ,idsl ) 

rtname   =   Sender  task  name  (If   not   specified,   data   may   be 
received  from  any  task,) 

ibuf    =   Address  of  15-word  buffer  to  receive  the  sender  task 
name  and  data 

ids      =   Integer  to  receive  the  Directive  Status  Word 

Macro  Call : 

RCST$    [tname] ,buf 

tname   =   Sender  Task  name  (If   not   specified,   data   may   be 
received  from  any  task.) 

buf      =   Address  of  a  15-word  buffer  to   receive   the   sender 
task  name  and  data 

Receive  Data  RCVD$ 

FORTRAN  Call  : 

CALL  RECEIV  ( [ tsk]  , buf [ ,  ,  ids ] ) 

tsk   =   Sender  task  name  (If  not  specified,  data  may  be 
received  from  any  task.) 

buf  =   A  15-word  integer  array  for  received  data 

ids  =   Directive  status 

Macro  Cal 1 : 

RCVD$  [tsk], buf 

tsk   =   Sender   task   name   (If   not   specified,   data   may   be 
received  from  any  task.) 

buf   =   Address  of  15-word  buffer 
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Receive  Data  Or  Exit  RCVX$ 

FORTRAN  Call : 

CALL  RECOEX  (  f tsk ] , buf [ , , ids] ) 

tsk   =   Sender   task   name   (If   not   specified,   data   may   be 
received  from  any  task.) 

buf   =  A  15-word  integer  array  for  received  data 

ids   =   Directive  status 

Macro  Call : 

RCVX$  [tsk], buf 

tsk   =   Sender   task   name   (If   not   specified,   data   may   be 
received  from  any  task.) 

buf   =  Address  of  15-word  buffer 

Read  All  Event  Flags  RDAfS 

FORTRAN  Call : 

A  FORTRAN  task  can  only  read  a  single  event  flag.   The  call  is: 
CALL  READEF  (efn[,idsl ) 

efn   --   Event  flag  number  (1-64.) 
ids   =  Directive  status 
Macro  Cal 1 : 

RDAF$   buf 

buf      =      Address   of    4-word    buffer 


f-{»^EV^'i*  iC  t. 


Read   Event   Flag  RI>Br$ 

FORTRAN  Call: 

CALL  READEF  (iefnt,id8)) 

iefn   =   Integer  containing  an  event  flag  number 
ids   ■   Integer  variable  to  receive  the  Directive  Status  Word 
Macro  Call: 

RDEF$     efn 
r  .^,^_  _■  efn   "  Event  flag  number 
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Read    Extended    Event    Flags  RDXP$ 

FORTRAN    Cflll : 

A   FORTRAN   task   can    read    only   a    single    event    flag.      The   rail    is: 
CALL    READEF    (efn[,ldsl ) 

efn      =      Event    flag    number    (1-96.) 
ids      =      Directive    status 
Macro   Cal 1 : 

RDXFS      buf 

buf   =   Address  of  6-word  buffer 

Remove  Affinity  {$S  form  reconmended)  RMAF$S 

FORTRAN  Call: 

CALL  RMAF   (  (ids) ] 

ids  "   Integer  to  receive  the  Directive  Status  Word 
Macro  Call: 

RMAFSS 

Request  and  Pass  Offspring  Information  RPOI$ 

FORTRAN  Call : 

CALL  RPOI  (tname, [ iugc! , [i jmc] , [ iparen] , [ ibuf 1 , ( ibfl 1 , [ IsTl , 

[ i task;  , [ocbad;  [ .ids]  ) 

tname  =  An  array  containing  the  actual  name  of  the  task  to  be 
requested  and  optionally  chained  to 

iugc  =  Integer  containing  the  group  ode  number  for  the  UIC 
of  the  requested  target  chain  cask 

i umc  =  Integer  containing  the  member  code  number  for  the  UIC 
of  the  requested  target  chain  task 

iparen  =  Array  (or  1*4  integer)  containing  the  RAD50  name  of 
the  parent  task  (This  is  returned  in  the  Information 
buffer  of  the  GTCMCI  subroutine.) 

Ibuf  =  Array  that  contains  the  command  line  text  for  the 
chained  task. 
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Isc  »  Flag  byte  controlling  the  actions  of  this  directive 
request  when  executed.  The  bit  dcf  >,  j  ns  of  this 
byte  are  as  follows: 

RP.OEX  =>  128.  Force  this  task  '.o  exit  on 
successful  execution  of  the  RPOI 
d  i  rect  ive  . 

RP.OAL  '  1  Pass  all  of  this  task's  OCBs  to  the 
requested  task.   (Default  is  none.) 

idnan  «  Integer  containing  the  ASCII  device  name  of  the 
requested  tasks  TI : 

iunit  =  Integer  containing  the  unit  number  of  the  requested 
tasks  TI:   device 

itask  =  Array  which  contains  the  RAD50  name  the  requested 
task  is  to  run  under.   (Valid  only  for  CLIs.) 

ocbad  =  Integer  containing  the  internal  pool  address  of  the 
parent  OCB  (Only  a  CLI  can  specify  this  argument 
because  the  value  can  only  be  obtained  in  the 
information  buffer  of  the  GTCMCI  subroutine.) 

Ids      =  Integer  to  receive  the  directive  status  word 

Macro  Cal 1  : 

RPOI$ 

tname, , , , [ugc] , [umc] , [parent! , [bufadr 1 , [buf len] , [sc] , [dnam] , 
[uni t] , [ tas] k, [ocba] d 

tname    =  'Name  of  task  to  be  chained  to 

ugc      «  Group  code  for  'JIC  of  the  requested  task 

umc     =  Member  code  for  UIC  of  the  requested  task 

parent  =  Name  of  Issuing  task's  parent  task  whose  OCB  is  to  be 
passed.   If  not  specified,  all  OCR's  are  passed. 

bufadr   =  Address  of  buffer  to  be  given  to  the  requested  task 

buflen  -    Length  of  buffer  to  be  given  to  requested  tasK 

sc      =  Flags  byte: 

RP.OEX    --    .'200)     Force    issuinc^    task    to    exit 
RP.OAL    --    fl)         Pass    all    OCBs 

dnam  =  ASCII    device    r.tme    for    TI: 

unit  "  Unit    number    of    tack    TI: 

task  =  RAD50   name   of    task    to    be    started 

ocbad  =  Address    of    OCB    to    pass    (CLIs   only) 
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Request  Task  RQSTS 

FORTRAN  Cal 1 : 

CALL  REQUES  ( tsk , [ opt ]  [  ,  Ids ) ) 

tsk   »   Task  name 

Oft   =   A  4-i^orJ  integer  array: 

opt(l)   »   Partition  name  first  half;   Ignored,   but 
!!iList  be  present 

opt(2)   »   Partition  name  second  half;   ignored,  but 
must  be  present 

opt(3)   =•   Priority;   Ignored,  but  must  be  present 

opt(4)   »   User  Identification  Code 

ids   =   Directive  status 
'  icro  Cal 1  : 

RQSTS   tsk, [prt I , fpr 1]  [  ,ugc ,arocl 

tsk   =   Task  name 

prt   =   Partition  name;   ignored,  but  must  be  present 

pr i   =   Priority;   ignored,  but  must  be  present 

ugc   =   UIC  group  code 

umc   -   UIC  member  code 

Receive  By  Reference  RREP$ 

FORTRAN  Call  : 

CALL  RREF    { i wdb , [ i sr b]  [ ,  ids] ^ 

iwdb    =      An    P-word    integer    array   containing    a   Window      Definition 
Block    (see    Section    3.5.2.2) 

isrb   =      A    10-word    integer    array      to      be      used      as      the      receive 
buffer 

ids  =      Directive    status 

Macro    Cal 1 : 

RREKS        wdb 

wdb  =      Window   Definition    Block 
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Resume  Task  RStJM$ 

FORTRAN  Call : 

CALL  RESUME  (tsk[,ids]) 
tsk   =   Task  name 
ids   =   Directive  status 
Macro  Call : 

RSUM$   tsk 

tsk   =   Task  name 

Run  Task  RUN$ 

FORTRAN  Call : 

CALL  RUN  {tsk, [opt] , [smg] ,snt, [rmg] , [rnt]  [,ids] ) 

tsk   =   Task  name 

opt   =   A  4-word  integer  array: 

opt(l)   =   Partition  name  first  half;   ignored,   but 
must  be  present 

opt(2)   =   Partition  name  second  half;   ignored,  but 
must  be  present 

opt(3)   =   Priority;   ignored,  but  must  be  present 

opt(4)   =   User  Identification  Code 

smg   =   Schedule  delta  magnitude  ' 

snt   =   Schedule  delta  unit 

rmg   =   Reschedule  interval  magnitude  / 

rnt   =   Reschedule  intervil  unit  / 

ids   =   Directive  status  / 

The  ISA  standard  call  for  initiating  a  task  is  also  include^: 

CALL  START  ( tsk  ,smg ,sn t [ , id  ■ ] ) 


tsk  =  Task  name 

smg  =  Schedule  delta  magnitude 

snt  =  Schedule  delta  unit 

ids  =  Directive  status 


/■ 
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Macro  Call  : 

RUN$  tsk, [prt 1 , [pr i] , [ugc] , [umc] , [smg] ,snt(,rmg,rnt; 

tsk  =  Task  name 

prt  =  Partition  name;   ignored,  but  must  be  present 

pt i  =  Priority;   ignored,  but  must  be  present 

ugc  =  UIC  group  code 

umc  =  UIC  member  code 

smg  =  Schedule  delta  magnitude 

snt  =  Schedule  delta  unit 

rmg  =  Reschedule  interval  magnitude 

rnt  =  Reschedule  interval  unit 

Supervisor  Call  ($$  fora  reconnended)  8CAL$8 

FORTRAN  Call: 

Not  supported 
Macro  Call : 

SCAL$S   saddr,caddr 

saddr   »  Address  of  the  called  sujiervisor-mode  routine 

caddr   >  Address  of  the  comp}etion  routine  for  return  to  the 
caller 

Set  Command  Line  Interpreter  SCLI$ 

FORTRAN  Call : 

CALL  SETCLI  ( icl i  ,  idev , i un i t [ , ids] ) 

Icli   =  A  two  word  array  element  containing  the  name  of  the  CLI 
to  which  the  terminal  is  to  be  set 

idev   =  Integer  containing  the  A"CII  name  of  the  terminal  to  be 
set  (default  =  TI : ) 

iunit  =  Integer  containing  the  unit  number  of  terminal 

ids  =  Directive  status 

Macro  Cal 1 : 

SCLIS  cli,  [dev] , [unit] 

cli  =  Name  of  the  CLI  to  which  the  terminal  is  to  be  set 

dev  =  ASCII  name  of  the  terminal  to  be  set  (default  =  TI:) 

unit  =  Unit  number  of  terminal 


A-24 


DIRECTIVE  SUMMARY  -  ALPHABETICAL  ORDER  BY  HACRO  CALL 

Send  Data  SDAT$ 

FORTHAN  Call : 

CALL  SEND  ( tsk  ,buf , [ ef n ]  [ ,  ids] ) 

tsk   =   Task  name 

buf      =      A    13-word    integer    array  of   data    to    be    sent 

efn      =      Event    flag    number 

ids      =      Directive    status 
Macro   Call : 

SDAT$      tsk, buf [, efn] 

tsk      =      Task   name 

buf      -      Address   of    13-word   data   butfer 

efn      =      Event    flag    number 

Send,  Request  And  Connect  SDRC$ 

FORTRAN  Call : 

CALL  SDRC  {rtname,lbuf ,[ iefn] ,[ last] ,[ iesb] ,[ iparm)  (, ids]  ) 


rtname 


Target   task   name   of   the   offspring   task   to   be 
connec  ted 


ibuf    =   Name  of  13-word  send  buffer 

iefn     =   Event  flag  to  be  set  when  the  offspring   task   exits 
or  emits  status 

last     =   Name  of   an   AST   routine   to   be   called   when   the 
offspring  task  exits  or  emits  status 

iesb    =   Name  of  an  fl-word  status  block  to   be   written   when 
the  offspring  task  exits  or  emits  status 

Word    0  —  Offspring  task  exit  status 

Word  1-7  --  Reserved 

iparm   =   Name  of  a  word  to  receive  the  status   block   address 
when  an  AST  occurs 

ids     =   Integer  to  receive  the  Directive  Status  Word 
Macro  Cal 1 : 

SDRCS    tname,buf , [efn] , [east] , (esb) 

tname   =   Target   task   name   of   the   offspring   task   to    be 
connected 


buf     =   Address  of  a  13-word  send  buff 


er 
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•fn    =   The  event  flag  to  be  cleared  on  issuance  and  when  the 
offspring  task  exits  or  emit  status 

east    =   Address  of  an  AST   routine   to   be   called   when   the 
offspring  task  exits  or  emits  status 

«ib    =   Address  of  a  8-word  status  block  to  be   written   when 
the  offspring  task  exits  or  emits  status 

Word    0  --  Offspring  task  exit  status 

Word  1-7  --  Reserved 


Send  Data  Request  and  Pass  Offspring  Control  Block  SDRP$ 

FORTRAN  Call : 

CALL  SDRP  (task,ibuf , ( ibfll  , [ iefn) , [ if  lag] , [ iparen]  , 
[ iocbad) [ , ids] ) 

task  =  Name  of  an  array  (REAL,  INTEGER,  1*4)  that  contains 
the  RAD50  name  of  target  task 

ibuf    =  Integer  array  containing  data  to  be  sent 

ibfl  =  Integer  containing  number  of  words  (integers)  in  the 
array  to  be  sent  (On  RSX-1 IM  systems,  this  argument 
must  be  13.,  and  on  RSX-1 1M-PLU55  systems,  this 
argument  may  be  in  the  range  of  1  to  25S.)  (Default  = 
13.) 

iefn  =  Integer  containing  the  number  of  the  event  flag  to  be 
set  when  this  directive  is  eyecuted  successfully 

iflag  =  Integer  containing  flags  bits  controlling  the 
execution.   They  are  defined  as  follows: 

SD.REX  =  128.   Force  this  task  to  exit 

upon  successful  execution 


SD.RAL 


Pass  all  OCBs 


iparen  =  Name  of  array  containing  the  RAD50  name  of  the   parent 
task  whose  OCB  should  be  passed  to  the  target  task 

iocbad  =  Name  of  an  integer  containing  internal  pool  address  of 
the  OCB  to  pass 

ids    =  Integer  to   receive   the   contents   of   the   Directive 
Status  Word 

Macro  Cal 1  : 

SDR PS  task,bufadr, [buflen] , [efn] , ( flag] , [parent] , (ocbad] 

task    =  Name  of  task  to  be  chained  to 

bufadr  =  Address  of  buffer  to  be  c,'iyen  to  the  requested  task 

buflen  =  Length  of  buffer  to  be  given  to  requested  task 
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efn    =  Event  flag 

flag    =  Flags  byte  (Force  exit,  pass  all  OCB's) 

parent  =  Name  of  issuing  task's  parent  task  whose  OCB  is  to   be 
passed 

ocbad   =  Address  of  OCB  to  pass  (CLI's  only) 

Set  Event  Flag  SETF$ 

FORTRAN  Call : 

CALL  SETEF  (efn[ , ids] ) 

efn   =   Event  flag  number 
ids   -   Directive  status 
Macro  Cal 1 : 

SETFS    efn 

efn   =   Event  flag  number 

Specify  Floating  Point  Exception  AST  SEPA$ 

FORTRAN  Call : 

Not  supported 
Macro  Call : 

SFPAS    [ast] 

ast   =   AST  service  routine  entry  point  address 

Send  Message  SIISG$ 

FORTRAN  Call : 

CALL  SMSG  (itgt.ibuf ,ibufl ,lprm,iprml,ids) 

itgt   =  Integer  containing  the  target  object 

ibuf   =  Integer  array  containing  the  data  to  be   inserted   into 
the  formatted  data  packet 

ibufl  =  Integer  containing  length  of  the  Ibuf  array 

iprm   =  Integer  afay  containing  any  additional  parameters 

iprml  =  Integer  containing  the  number  of  parameters  in  the  iprm 
array 

ids    =  Optional  integer  to  receive  the  directive  status 
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Macro  Cal 1  : 

SMSGS   tgt,buf ,len,<pr I , . . . ,prn> 
t9t  »     Target    identifier 

kitf  »      Address   of   optional    data    buffer 

len  =      Length    In   bytes   of    optional    data    buffer 

pri,...,prn      =      Target-specific    parameter    list: 
Parameter    list    for    Error    Logging 

SMSGS    SM.SER,buf , len ,typ,sub, lun ,mask> 
typ      =    Error    Log    packet    code 
sub      =    Error    Log    packet    subtype    code 
lun      =    Logical    unit    number    of   device 
msk      =   Control    mask    word 

Send  Next  Coamand  SNXCC 

FORTRAN  Call: 

CALL  SNXC  ( (dna«)[,lunlt) {,idal ) 

dnam   *  Device  name  (ASCII).   If  not  specified,  TI :   is  used. 

iunit  ■  Unit  number  of  the  terminal  from  which  the  command   is 
to  be  sent. 

ids   =  Integer  to  receive  the  directive  status  word. 

Macro  Call: 

SNXCS    (dnamH»unum] 

dnam      =»   Device   name    (ASCII).      If    not    specified,    TI:       is   used. 

unuro      »   Unit   number   of    the   terminal    from   which   the     command      Is 
to    be   sent. 

Specify   Parity  Error   AST  SPBA$ 

FORTRAN  Call: 

Not    supported 
Macro   Call: 

SPEAS    (astl 

ast  *     AST  services  routin(>  entry  point  address 
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Suspend  ($S  form  recommended)  SPIIO$S 

FORTRAN  Call  : 

CALL  SUSPND    [  (Ids)  ] 

Ids   =  Directive  status 
Macro  Cal 1 : 

SPND$S   [err] 

err   =   Error  routine  address 

Specify  Power  Recovery  AST  SPKAS 

FORTRAN  Call : 

EXTERNAL  sub 

CALL  PWR'JP  (sub) 

sub  =  Name  of  a  subroutine  to  be  executed  upon  power 
recovery.  The  PWRUP  subroutine  will  effect  the 
f o 1 lowi  nq : 

CALL  sub  (no  arguments) 

The  subroutine  Is  called  as  a  result  of  a  power 
recovery  AST,  and  therefore  the  subroutine  can  be 
controlled  at  critical  points  by  using  the  DSASTR  (or 
INASTR)  and  ENASTR  subroutine  call'.. 

To  Remove  an  AST: 

CALL    PWRUP 
Macro    Cal 1  : 

SPRA$       [ast] 

ast   =   AST  service  routine  entry  point  address 

Spawn  RPWNS 

FORTRAN  Cal 1 : 

CALL  SPAWN  (rtname, [ iuqc] , [ lumc) , [ iefn] , [ last] , [  lesbl , ( iparm]  , 
[ irml in] , [ icmlen] , f  >uni  t) , [dnam)  [  ,  ids] ) 

rtname   =   Name  (RAD50)  of  the  offsprinc  task  to  be  spawned 

luge     =   Group  code  number  for  the  UIC  of  the  offspring  task 

iumc     =   Member  code  n'lmber  for  the  UIC  of  the  offspring  task 

iefn     =   Event  flag  to  be  set  when  the  offspring   task   exits 
or  emits  status 

last     =   Name  of   an   AST   routine   to   be   called   when   the 
offspring  task  exits  or  emits  status 
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iesb  =  Name  of  an  8-word  status  block  to  be  written  when 
the  offspring  cask  exits  or  emits  status 

Word    0  —  Offspring  task  exit  status 

Word  1-7  --  Reserved 

iparm  =  Name  of  a  word  to  receive  the  status  block  address 
when  the  AST  occurs 

icmlin  =  Name  of  a  command  line  to  be  queued  for  the 
offspring  task 

icmlen  =   Length  of  the  command  line  (79.   characters  maximum) 

iunit  =  Unit  number  of  terminal  to  be  used  as  the  TI :  for 
the  offspring  task  (If  the  optional  dnam  parameter 
is  not  specified,  this  parameter  must  be  the  unit 
number  of  a  virtual  terminal  created  by  the  Issuing 
task;  if  a  value  of  0  is  specified,  the  TI:  of  the 
issuing  task  is  propagated.) 

dnam  =  Device  name  mnemonic  (If  not  specified,  the  virtual 
terminal  is  used  as  TI : . ) 

ids      =   Integer  to  receive  the  Directive  Status  Word 

Macro  Call ! 

SPWN$    tni-me, ,  ,  [ugc]  ,  [umc]  ,[efn],[east],  [esb]  ,  [cmdl  in]  ,  [cmdlen] 
,  [ unum] , [dnam] 

tname    =  Name  (RAD50)  of  the  offspring  task  to  be  spawned 

ugc     =  Group  code  number  for  the  UIC  of  the  offspring  task 

IUQ.O     =   Member  code  number  for  the  UIC  of  the  offspring  task 

•fR  =  The  event  flag  to  be  cleared  on  issuance  and  set 
when  the  offspring  task  exits  or  emits  status 

east  =  Address  of  an  AST  routine  to  be  called  when  the 
offspring  task  exits  or  emits  status 

eab  =  Address  of  an  8-word  status  block  to  be  written  when 
the  offspring  task  exits  or  emits  status 

Word    0  --  Offspring  task  exit  status 

Word  1-7  --  Reserved 

cmdlin  =  Address  of  a  command  line  to  be  queued  for  the 
offspring  task 

cmdlen   =   Leng*-.h  of  the  command  lin«?  (maximum  length  is  79.) 

unum  =  Unit  number  of  terminal  to  be  used  as  the  TI:  for 
the  offspring  task  (If  the  optional  dnam  parameter 
is  not  specified,  this  parameter  must  be  the  unit 
number  of  a  virtual  terminal  created  by  the  issuing 
task;  if  a  value  of  0  is  specified,  the  TI :  of  the 
issuing  task  is  propagated.) 
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dnam    =   Device  name  mnemonic  (If  not  specified,  the  virtual 
terminal  is  used  as  TI : . ) 

NOTE 

1.  If  neither  unum  nor  dnam  is  specified, 
the  TI:  of  the  issuing  task  Is 
propagated . 

i.  If  only  unum  is  specified,  TI:  is  a 
virtual  terminal. 

Specify  Receive  Data  AST  SRDA$ 

FORTRAN  Call : 

Not  supported 
Macro  Call : 

SRDA$    [ast] 

ast   =   AST  service  routine  entry  point  address 

Specify  Requested  Exit  AST  SREA$ 

SREX$ 

FORTRAN  Call : 

CALL  SREA  (ast[ .ids] ) 

ast  =  Namo  ot  the  «:;cternaliy  declared  '^^T  "subroutine 

ids  =  Natt.e  of  an  optional   integer   to   receive   the   Directive 
Status  Woid 

CALL  3REX  (ast , i pbl k , i pbl kl ,[ dummy]  [,  ids] ) 

ast    =  Name  of  the  externally  declared  AST  subroutine 

ipblk  -  Name  of  an  integer  array  lo    receive  the   trap-dependent 
parameters 

ipblkl  -  Number  of  parameters  to  be   returned   into   the   ip''k 
array 

dummy  =  Reserved  for  future  use 

ids    =  Name  of  an  optional  integer  to   receive   the   Directive 
Status  Word 

Macro  Call : 

SREA$  [ast] 

SREX$  [ast] [ , dummy] 

ast    =  AST  service  routine  entry  point  address 

dummy  =  Reserved  for  future  expansion 
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Send  By  Reference  SREP$ 

FORTRAN  Call : 

CALL  SREF  ( tsk , [ ef n ) , I wdb , [ I sr b) [ , Ids] ) 

tsk   =   Receiver  task  name 

efn      =      Event    flag   x>Limber 

Iwdb   =      An    8-word    Integer    array   containing    a   Window      Definition 
Block    (see    Section    3.5.2.2) 

Isrb  =      An        8-word  nteger        array        containing         additional 

information 

ids      =      Directive    status 

Macro   Cal 1  : 

i,REF$    task, wdb[, efn] 

task  =   Receiver  task  name 

wdb   =  Window  Definition  Block  address 

efn   =   Event  flag  number 

Specify  Receive-By-Reference  AST  SRRA$ 

FORTRAN  Call : 

Not  supported 
Macro  Cal 1  : 

SRRA$   [ast] 

ast   =   AST  service  routine  entry  point  address 

Set  Affinity  STAP$ 

FORTRAN  Call: 

CALL  STAF  (iaff [,ids] ) 

iaff  ■  Affinity  mask  word 

ids  »   Integer  to  receive  Directive  Status  Word 
Macro  Call: 

STAP$  (cplublub.. . ] 

cp  =  CPU  selected  (A  through  D) 

ub   =  UNIBUS  run(s)  selected  (E  through  T) 
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Set  System  Time  Directive  STIII$ 

FORTRAN  Call : 

CALL  SETTTM  { Ibuf n [ , 1 buf p)  [ ,  Ids] ) 

Ibufn  =  An  8-word  Integer  array,  new  time  specification  buffer 
ibufp  =  An  8-word  Integer  array,  previous  time  buffer 
Ids    =  Directive  status 
Macro  Call  : 

STIM$  bufn, [bufp] 

bufn   =  Address  of  8-word  new  time  specification  buffer 

bufp   =  Address  of  8-word  buffer  to  receive  the  previous  system 
time  parameters 

Stop  For  Logical  OR  Of  Event  Flags  STLO$ 

FORTRAN  Call : 

CALL  STLOR  ( ief 1 , I ef 2, I ef 3,  ...   ief(n)) 

iefl  ...   ief(n)   =   List  of  event  flag  numbers 
Macro  Cal 1  : 

STLOS    grp,  msk 

grp      =      Desired   group  of   event    flags 
msk      =      A    16-bit   mask   word 

Stop  <$S  form  recommended)  STOP$S 

FORTRAN  Call : 

CALL  STOP  ([ids] ) 

ids   =   Integer  to  receive  the  Directive  Status  Word 
Macro  Cal 1  : 

STOP$S 

Stop  For  Single  Event  Flag  3TSK$ 

FORTRAN  Call : 

CALL  STOPFR  (iefn[,idsl) 

lefn  =   Event  f ' ig  number 

ids   =   Integer  to  receive  Directive  Status  Word 
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Macro  Cal 1 : 

STSES    efn 

efn   =   Event  flag  number 

Specify  SST  Vector  Table  For  Debugging  Aid  SVDB$ 

FORTRAN  Call : 

Not  supported 
Macro  Cal 1 : 

SVDB$   [adr][,len] 

adr   =   Address  of  SST  vector  table 

len   =   Length  of  (that  is,  number   of   entries   in)   table   In 
words 

Specify  SST  Vector  Table  For  Task  SVTK$ 

FORTRAN  Call : 

Not  supported 
Macro  Cal 1 : 

SVTK$   [adr]  r,lenl 

adr   =   Address  of  SST  vector  table 

len   =   Length  of  (that  is,  number   of   entries   in)   table   in 
words 

Unlock  Group  Global  Event  Flags  ($S  forn  recommended)  ULGP$S 

FORTRAN  Call : 

CALL  ULGF  ( [ ids] ) 

ids  =  Directive  status 
Macro  Cal 1  : 

ULGF$S  r,errl 

err  =  Error  routine  address 

Unmap  Address  Window  UNIIAPS 

FORTRAN  Call: 

CALL  UNMAP  (iwdb[,ids]) 

iwdb   =      An    8-word    integer    array  containing    a   Window      Definition 
Block     (see    Section    3.5.2.2) 

ids   =   Directive  status 
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DIRECTIVE  SUMMARY  -  ALPHABETICAL  ORDER  BY  HACRO  CALL 

Macro  Cal 1 : 

UMAPS    wdb 

wdb   =   Window  Definition  Block  address 
Unstop  TASK  USTPS 

FORTRAN  Call : 

CALL  USTP  (rtnamet , ids] 1 

rtname   =   Name  of  task  to  be  unstopped 

Ids      =   Integer  to  receive  directive  status  information 
Macro  Cal 1 : 

USTPS    tname 

tname    =   Name  of  task  to  be  unstopped 

Variable  Receive  Data  "  -^r-^-a,r    vrcd$ 

FORTRAN  Call : 

CALL   VRCD    {[task]  ,bufadr,(bufl8nHrld8)  ) 

task     *      Sender  task  name 

bufadr   *  Address  of  buffer  to  receive  the  sender   task  name 
and  data 

buflen  "!  Length  of  buffer 

ids  =  Integer  to  receive  the  Directive  Status  Word 

Macro  Cal 1  : 

VRCDS       [task] ,bufadrf, buflen] 

task  =  Sender  task  name 

bufadr  *  Buffer  address 

buflen  =  Buffer  size  in  words 

Variable  Receive  Data  Or  Stop  VRCS$ 

FORTRAN  Call : 

CALL  VRCS  ([task] ,bjfadr, [buflen] [, ids] ) 

task     »   Sender  task  name 

buf     =   Address  of  buffer  to  receive  the   sender   task   nain»» 
and  data 

buflen   "   Length  of  buffer 

„       ids      =   Integer  to  receive  the  Directive  Status  Word 
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DIRECTIVE  SUMMARY  -  ALPHABETICAL  OHDEH  BY  MACRi)  CALL 

Macro  Call : 

VRCS$       [task! ,bufadr[,buflen] 

task  =   Sender  task  name 

bufadr  =   Buffer  address 

butlen  =   Buffer  size  in  words 

Variable  Receive  Data  Or  Exit  VKCXS 

FORTRAN  Call : 

CALL  VRCX  ([task] , bufadr, [buflen]  r .Ids] ) 

task     =   Sender  task  name 

bufadr   =   Address  of  Suffer  to  receive  the   sender   task   nas* 
and  data 

buflen  =  Length  of  b'iffer 

ids  =  Integer  to  receive  the  Directive  Status  Word 

Macro  Cal 1 : 

VRCX$  [task] ,bufadr(, buflen] 

task  =  Sender  task  name 

bufadr  =  Buffer  addrers 

buflen  =  Buffer  size  in  words 

Variable  Send  Data  VSDA$ 

FORTRAN  Call  :  ' 

CALL  VSDA  ( [task]  ,bufsdr, [buflen]  , [efn]  [.ids]  ) 

task     =   Receiver  task  name 

bufadr   =   Address  of  buffer  to  receive  the   sender   task   name 
and  data 

buflen  =  Length  of  buffer 

efn  =  Event  flag  number 

ids  =  Integer  to  receive  the  Directive  Shatus  Word 

Macro  Cal 1  : 

VSDAS  [task] ,buf ad r , [buflen]  [,efn] 

^  — —         task  =  Receiver    task    name 

bufadr  =  Buffer    address 

buflen  =  Buffer    size    in   words 

efn  =  Event    flag    number 
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DIRECTIVE  SUMMARY  -  ALPHABETICAL  ORDER  BY  MACRO  CALL 

Variable  Send,  Request  and  Connect  VSRC$ 

FORTRAN  Call: 

CALL  VSRC  (rtname,ibuf ,[ibuflen] , [iefn] , [last] , [iesb] , [ iparm][ ,ld8] ) 

rtname  =  Target   task  name  of   the  offspring   task   to   be 
connected 

ibuf    =  Name  of  13-word  s >nd  buffer 

ibuflen  =  Length  of  buffer 

iefn    =  Event  fla.,-  t.,  be  set  when  the  offspring   task  exits 
or  emits  status 

last    »  Name  of  an  AST  routine   to   be  called   when   the 
offspring  task  exits  or  emits  status 

iesb    =  Name  of  an  8-word  status  block  to  be  written  when 
the  offspring  task  exits  or  emits  status 

Word    0  —  Offspring  task  exit  status 

Word  1-7  —  Reserved 

iparm   =  Name  of  a  word  to  receive  the  status  block  address 
when  an  AST  occurs 

ids     =   Integer  to  receive  the  Directive  Status  Word 

Macro  Call: 

VSRC$    tname,buf [ ,buf len] ,efn,e3st ,esb 

tname   =  Target   task  name  of   the   offspring   task   to   be 
connected 

buf     =  Address  of  a  13-wcrd  send  buffer 

buflen  =  Length  of  buffer 

efn     =  The  event  flag  to  be  cleared   on   issuance  and   set 
when  the  offspring  task  exits  or  emits  status 

east    =  Address  of  an  AST  routine   to   be  called   when   the 
offspring  task  exits  or  emits  status 

esb     =  Address  of  a  8-word  status  block  to  be  written  when 
the  offspring  task  exits  or  emits  status 

Word   0  —  Offspring  task  exit  status 

Word  !  -7  —  Reserved 


IE, 

.  lOP 

-83. 

IE. 

,ALG 

-84. 

IF, 

WOV 

-85. 

IE. 

NVR 

-86. 

IE. 

NVW 

-87. 

IE. 

ITP 

-88. 

IE. 

IBS 

-89. 

IE. 

LNL 

-90. 

IE. 

lUI 

-91. 

IE. 

IDU 

-92. 

IE. 

ITI 

-93. 

IE. 

.  PNS 

-94. 

IE. 

I  PR 

-95. 

IE. 

ILU 

-96. 

IE, 

,  lEF 

-97. 

IE. 

ADP 

-98. 

IE. 

,  SDP 

-99. 

STANDARD  ERROR  CODES 


WINDOW  HAS  I/O  IN  PROGRESS 

Ar.IGNMENT  ERROR 

ADDRESS  WINDOW  ALLOCATION  OVERFLOW 

INVALID  REGION  ID 

INVALID    ADDRESS    WINDOW    ID 

INVALID    TI    PARAMETER 

IN'ALID    SEND    BUFFER    SIZE     v>255.) 

LUN    LOCKED    IN    USE 

INVALID    UIC 

INVALID  DEVICE  OR  UNIT 

INVALID  TIME  PARAMETERS 

PARTITION/REGION  NOT  IN  SYSTEM 

INVALID  PRIORITY  (>250.) 

INVALID  LUN 

INVALID    EVENT    FLAG    NUMBER 

PART    OF    DPB    OUT    OF    USER'S    SPACE 

Die    OR    DPB    SIZE    INVALID 
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APPENDIX  C 
DIRECTIVE  IDENTIFICATION  CODES 


Directive  Identification  Codes  (DICs)  are  used  to  identify  each 
directive.  The  DIG  appears  in  the  low  byte  of  the  first  (or  only) 
word  in  the  Directive  Parameter  Block  (DPB) .  The  DPB  length  (in 
words)  appears  in  the  hiqh  byte  of  the  first  DPB  word.  Thus,  both 
bytes  make  up  the  word  format  shown  below: 


First  Word 
In  DPB 


L»PB  Length 

Die 

(Hign  byte) 


(Low  byte) 


The  remainder  of  this  appendix  contains  a  listing  of  directives 
arranged  in  numerical  sequence,  according  to  the  octal  va^ ue  for  the 
first  DPB  word.  In  addition,  the  DIG  and  DPB  lengths  are  included  as 
decimal  values  as  they  appear  in  Chapter  5. 

This  list  can  be  used  as  a  software  debugging  aid  to  quickly  identify 
directives  based  on  the  octal  value  of  the  first  word  in  a  DPB.  vn 
example  for  the  SDATS  directive  is  provided  below,  illustrating  the 
manner  in  which  the  octal  value  is  obtained: 


First  Word 
In  DPB 


5(10) 

...      ,  , 

71(10) 

Otlal  Byte 
Values 


5(8) 


107(8) 


Binary  Word 
Value 

Octal  Word 
Value 


101 


01 


000 


2507  (    SDATS) 


111 


ZKIU  81 


G-1 


DIRECTIVE  IDENTIFICATION  CODES 


Octal  Value  For 

Directive 

Dbcimal 

Values  For 

DPB  First  Word 

(Macro  Call) 

Die 

DPB  T.enqth 

433 

CMKT$ 

27. 

HI 

DECL$S 

39«. 

4SS 

SPNDSS 

45. 

461 

WSIGSS 

49. 

4fi3 

EXITSS 

51. 

Sft 

DSCPSS 

95.  , 

HI 

ENCP$S 

97. 

143 

DSAR$S  or  IHAR$S 

99. 

Hi 

ENAR$S 

101. 

563 

ASTXSS 

115. 

«           ^  ^ 

575 

GSSWSS 

125. 

602 

STOpeS 

131. 

637 

ULGFSS 

159. 

643 

RMAF$S 

163. 

1015 

STAF$ 

13. 

1025 

SRRA$ 

21. 

2. 

1035 

EXS'r$ 

29. 

2. 

1037 

CLEFS 

31. 

2. 

1041 

SETFS 

33. 

2. 

1047 

RDAFS 

39. 

2. 

1051 

WTSES 

41. 

2. 

1065 

EXIF$ 

53. 

2. 

1067 

CRRGS 

55. 

2. 

1071 

ATRGS 

57. 

2. 

1073 

DTRG$ 

59. 

2. 

1075 

GTIMS 

61. 

2. 

1077 

GTSKS 

63. 

2. 

1121 

RREFS 

81. 

2. 

1153 

SRDAS 

107. 

2. 

1155 

SPRAS 

109. 

2. 

1157 

SFPAS 

111. 

2. 

1161 

GMCXS 

113. 

2. 

1165 

CRAW$ 

117. 

2. 

1171 

MAPS 

121. 

2. 

1173 

UMAPS 

123. 

2. 

1207 

STSES 

135. 

2. 

1227 

ELVTS 

151. 

2. 

1235 

CRGFS 

1  S7. 

2. 

1237 

ELGFS 

159. 

2. 

1241 

STAP$      -r--T 

161.  " 

2. 

1245 

SPEA$ 

165. 

2. 

1247 

SREA$ 

167. 

2. 

1405 

GLUNS 

5. 

3. 

1431 

CSRQS 

25. 

3. 

M33 

CMKTS 

27. 

3. 

1447 

RDXFS 

39. 

3. 

1453 

WTLOS 

43. 

3. 

1457 

RSUMS 

47. 

3. 

1475 

STIMS 

61. 

3. 

1523 

ABRT$ 

83. 

3. 

1531 

EXTKS 

89. 

3. 

1547 

SVDBS 

103. 

3. 

1551 

SVTKS 

105. 

3. 

1605 

USTPS 

133. 

3. 
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DIRECTIVE  IDENTIFICATION  CODES 


Octal  Value  For 
DPB  First  Word 


1611 
1617 
1633 

1647 
2007 
2011 
2101 
2113 
2115 
2213 
2223 
2427 
2505 
2507 
2625 
3113 
3115 
3213 
3413 
3601 
3615 
4107 
5421 
6001 
6003 
6413 
7013 
24577 


Directive 

Deciaal 

Val 

lies  For 

(Macro  Call) 

Die 

DPB 

Length 

STLO$ 

137. 

3. 

CNCT$ 

143. 

3 

SCAL$S 

155. 

3. 

SREX$ 

167. 

3 

ALUN$ 

7. 

4 

ALT  PS 

9. 

4. 

GPRTS  or  GREG$ 

65. 

4. 

RCVDS 

75. 

4 

RCVXS 

77. 

4. 

RCST$ 

139. 

4. 

EMSTS 

147. 

4 

MRKTS 

23. 

5 

SREFS 

69. 

5 

SDAT$ 

71. 

5 

CRVT$ 

149. 

5 

VRCDS 

75. 

6 

VRCX$ 

77. 

6 

VRCSS 

139. 

6 

RQSTS 

11. 

7 

CINTS 

129. 

7 

SDRC$ 

141. 

7 

vsnA$   ^  ^'MMKii„JU*  JR^« 

8 

RUN? 

17. 

n. 

QIOS 

1. 

12. 

grows 

3. 

12. 

SPWNS 

H. 

13. 

SPWNS 

11. 

14. 

GMCRS 

127. 

4 
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APPENDIX  D 
RSX-11  SYSGEN  SELECTION  OP  EXECUTIVE  DIRECTIVES 


The  following  list  contains  all  Executive  directive  macro  calls 
described  in  this  manual  and  means  of  selection  at  SYSGEN  time.  Those 
directives  not  ivailable  for  specific  RSX-11  systems  are  noted  as  N/A. 
Directives  that  are  SYSGEN  options  are  noted  as  0.  The  number  in 
parentheses  after  the  0  refers  to  the  SYSGEN  options  at  the  end  of  the 
list.  Llrectives  that  are  standard  (not  SYSGEN  options^  are  indicated 
by  an  asLjr Isk  (*) . 


Direct  i ve 

Macro 

Call 


ABRT$ 

ALT  r^ 

ALUN$ 

ASTX$S 

ATRGS 

CINTS 

CLEFS 

CMKT$ 

CNCTS 

CPCR$ 

CRAWS 

CRGF? 

CRRGS 

CRVTS 

CSRQS 

DECLSS 

DSARSS 

DSCPSS 

DTRGS 

ELAWS 

ELGFS 

ELVTS 

EMSTS 

ENARSS 

ENCPSS 

EXIFS 

EXITSS 

EXSTS 

EXTKS 

GCCIS 

ecus 

GLUNS 

GMCRS 

GMCXS 

GPRTS 

GREGS 

GSSWSS 

GTIM$ 


or  IHARSS 


Systea  Type 

RSX-llS 

RSX 

-IIM 

RSX 

-1  in 

* 

* 

0  (1) 

0 

(1) 

* 

* 

0  (2) 

0 

(2) 

0  (3» 

0 

(3) 

0  (1) 

0 

(1) 

* 

• 

* 

* 

0  M) 

0 

(4) 

M/A 

N/A 

0  (3) 

0 

(3) 

0  (5) 

0 

(5) 

0  (3) 

0 

(3) 

N/A 

* 

N/A 

* 

(6) 

* 

* 

0  (2) 

0 

(2) 

N/A 

0 

'7) 

0  (3) 

0 

(3) 

0  (3) 

0 

(3) 

0  (5) 

0 

{^) 

M/A 

N/A 

(6) 

0  (4) 

0 

(4) 

0  (2) 

0 

(2) 

N/A 

0 

(7) 

• 

* 

* 

* 

0  (4) 

0 

(i) 

0  (1) 

0 

(1) 

N/A 

0 

(15) 

(15) 

N/A 

0 

(15) 

(15) 

* 

• 

N/A 

* 

0  (3) 

0 

(3) 

0  a) 

0 

(1) 

0  (3) 

0 

(3) 

0  (1) 

0 

(1) 

• 

* 
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Dl  rect 1 ve 

Macro 

Call 

GTSK$ 

MAPS 

MHKT$ 

MSDS$ 

MVTS$ 

QIO$ 

QIOWS 

RCSTS 

nCVDS 

RCVXS 

RDAFS 

RDEF$ 

RDXFC 

RMAF$S 

HfOI$ 

ROSTS 

RREFS 

RSUMS 

RUNS 

SCAA$ 

SCALSS 

SC  L  I  $ 

j;dat$ 

SDRCS 

SDkPS 

GETFS 

SFPAS 

SMSG$ 

SNXC$ 

SPEAS 

SPNDSS 

SPRAS 

SPWNS 

SRDAS 

SREAS 

SREFS 

SREXS 

SRRAS 

SRRC$ 

STAP$ 

5TIM$ 

STLOS 

STOPSS 

STSES 

SVDBS 

SVTKS 

ULGFSS 

UMAP$ 

USTPS 

VRCD$ 

VRCSS 

VRCXS 

VSDAS 

VSRC$ 

WSIGSS 

WTLOS 

WTSES 


Syatea  Type 

;x-iis 

RSX-1  1« 

Rnx-UM- 

0  (1) 

0  (1) 

0  (3) 

0  (3) 

* 

* 

Pfh 

N/A 

0  ao) 

N/A 

N/A 

0  (16) 

* 

* 

• 

• 

0  (13,14) 

0  (13,14) 

0  (14) 

0  (14) 

0  (14) 

0  (14) 

» 

* 

H/A 

V./K 

-^\        <   t"_   N 

3  c:') 

N/A 

N/A 

0  (8) 

C  (1,4) 

0  (1,4) 

* 

• 

0  (1, 3) 

0  (1,1) 

• 

• 

* 

* 

N/A 

0  (15) 

0  (IS, 

N/A 

N/A 

0  (9) 

N/A 

0  (I'j) 

0  (15) 

0  (14) 

0  (14) 

0  (4,  14) 

0  (4,14) 

N/A 

0  (14,15) 

* 

* 

0  •2,  10) 

0  (2,  10) 

0  (10) 

N/A 

0  (12) 

N/A 

N/A 

N/A 

N/A 

• 

* 

0  (2,  11) 

0  (2,  11) 

0  (4) 

0  (4, 

0  (2,  14) 

0  (2,  14) 

0  (1,2) 

0  (1,2) 

0  (1,3)  • 

0  (1,3) 

0  (1,2) 

0  (1,2) 

0  (1,  2,  3) 

0  (1,  2,  3) 

N/A 

N/A 

N/A 

N/A 

0  (8) 

0  fl) 

1  (I) 

0  (13) 

0  (13) 

0  (13) 

0  (1  \) 

0  (13) 

0  (13) 

* 

* 

* 

* 

0  (5) 

0  (5) 

0  (3) 

0  (3) 

0  (13) 

0  (13) 

N/A 

N/A 

N/A 

N/A 

N/A 

N/A 

N/A 

N/A 

M/A 

N/A 

* 

* 

* 

• 

* 

* 
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RSX-11    SYSGEN    SELECTION    OF    EXEC'JTIVE    'DIRECTIVES 

SYSGEN  Options: 

1.  Specific  Executive  directive  support 

2.  AST  support 

3.  Memory  management  directives 

4.  Parent/offspring  tasking  support 

5.  Group-global  event  ?lag  support 

6.  Virtual  terminal  support 

7.  Checkpointing  support 

8.  Multiprocessor  support 

9.  Supervisor-mode  library  support 

10.  Floati.ig  Point  Processor  support 

11.  Powerfail  recovery  support 

12.  Error  Logging  support 

13.  Stop  bit  synchronization  support 

14.  Send/receive  support 

15.  Alternate  CLI  support 

16.  D-space  support 
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INDEX 


Abort  Task,  5-8 
ABRTS,  5-a 

Address  mapping,  3-2 
Address  space, 

logical,  3-2,  3-4 

physical ,  3-2 

virtual,  3-2,  3-4 
Address  window, 

vi  rtual ,  3-3 
Addressing , 

PDP-11,  3-1 
Affinity,  5-128 

removing,  5-128 

setting,  5-193 
Alter  Priority,  5-10 
ALTPS,  5-10 
ALUNS,  5-12 
Assign  LUN,  5-12 
AST, 

conmand  arrival,  5-145 

definition,  2-4 

exit,  5-184 

floating  point  processor 
exception,  5-160 

general  characteristics,  2-7 

parity  error,  5-167 

power  recovery,  5-170 

purpose,  2-fi 

receive  data,  5-182 

rece i ve-by-ref erence ,  5-191 

service  routine,  2-7 

task's  stack  format, 
2-8  to  2-11 

trap-dependent  parameters, 
2-8 
AST  recognition,  5-53  to  5-54 
AST  routine, 

FORTRAN  callable,  1-16 
AST  Service  Exit,  5-14 
ASTX3S,  5-14 
Asynchronous  System  Trap 

(AST) ,  2-4 
ATRGS,  5-16 
Attach  Region,  5-16 
Attachment  descriptor,  3-9 


Batch  processing,  4-1 

Buffer  format, 

for  GTIMS  directive,  5-95 
for  GTSKS  directive,  5-97 


$C  macro  form,  1-6 

CALL 

ABORT,  5-8 

CALL 

ALTPRI, 

5-10 

CALL 

ASNLUN, 

5-12 

CALL 

ATRG,  5- 

-16 

CALL 

CANALL, 

5-51 

CALL 

CANMT,  ' 

S-29 

CALL 

CLREF,  ■ 

5-28 

CALL 

CNCT,  5- 

-31 

CALL 

CPCR,  5- 

-34 

CALL 

CRAW,  5- 

-37 

CALL 

CRGF,  5- 

-4C 

CALL 

CRRC,  5- 

-42 

CALL 

CRVT,  5- 

-48 

CALL 

DECL'R, 

5-5? 

CALL 

DISCKP, 

5-55 

CALL 

DSAS-^R, 

5-53 

CALL 

DTRG,  5 

-56 

CALL 

ELAW,  5 

-58 

CALL 

ELGF,  5 

-60 

CALL 

E  LVT ,  5 

-62 

CALL 

EMST,  5 

-64 

CALL 

ENACKP, 

5-fi6 

CALL 

ENASTR, 

5-65 

CALL 

EXIT,  5 

-70 

CALL 

EXITIF, 

5-67 

CALL 

EXST,  5 

-71 

CALL 

EXTTSK, 

5-73 

CALL 

GETCII, 

5-79 

CALL 

GETLUN, 

5-81 

CALL 

GETMCR, 

5-84 

CALL 

GETPAR, 

5-89 

CALL 

GETREG, 

5-91 

CALL 

GETTIM, 

5-95 

CALL 

GETTSK, 

5-97 

CALL 

GMCX,  5 

-86 

CALL 

GTCMCI, 

5-75 

CALL 

INASTR, 

5-53 

CALL 

MAP,  5- 

100 

CALL 

MARK,  5 

-103 

CALL 

PWRUP, 

5-170 

CALL 

010,  5- 

112 

CALL 

RCST,  5 

-118 

CALL 

READEF, 

5-125, 

CALL 

RECEIV, 

5-120 

CALL 

RECOEX, 

5-122 

CALL 

RESUME, 

5-139 

CALL 

RMAF,  5 

-128 

CALL 

RPOI,  5 

-129 

CALL 

RREF,  5 

-136 

CALL 

RUN,  5- 

140 

CALL 

SDRC,  5 

-152 

5-127 
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INDEX 


CALL  SDRP, 
CALL  SEND, 
CALL  SETCLI 
CALL  SETEF, 
CALL  SETTIM 
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